1 \section{\class{wxImage
}}\label{wximage
}
3 This class encapsulates a platform-independent image. An image can be created
4 from data, or using
\helpref{wxBitmap::ConvertToImage
}{wxbitmapconverttoimage
}. An image
5 can be loaded from a file in a variety of formats, and is extensible to new formats
6 via image format handlers. Functions are available to set and get image bits, so
7 it can be used for basic image manipulation.
9 A wxImage cannot (currently) be drawn directly to a
\helpref{wxDC
}{wxdc
}. Instead,
10 a platform-specific
\helpref{wxBitmap
}{wxbitmap
} object must be created from it using
11 the
\helpref{wxBitmap::wxBitmap(wxImage,int depth)
}{wxbitmapctor
} constructor.
13 be drawn in a device context, using
\helpref{wxDC::DrawBitmap
}{wxdcdrawbitmap
}.
15 One colour value of the image may be used as a mask colour which will lead to the automatic
16 creation of a
\helpref{wxMask
}{wxmask
} object associated to the bitmap object.
18 \wxheading{Alpha channel support
}
20 Starting from wxWidgets
2.5.0 wxImage supports alpha channel data, that is in
21 addition to a byte for the red, green and blue colour components for each pixel
22 it also stores a byte representing the pixel opacity. An alpha value of $
0$
23 corresponds to a transparent pixel (null opacity) while a value of $
255$
24 means that the pixel is
100\% opaque.
26 Unlike RGB data, not all images have an alpha channel and before using
27 \helpref{GetAlpha
}{wximagegetalpha
} you should check if this image contains
28 an alpha channel with
\helpref{HasAlpha
}{wximagehasalpha
}. Note that currently only
29 images loaded from PNG files with transparency information will have an alpha
30 channel but alpha support will be added to the other formats as well (as well
31 as support for saving images with alpha channel which also isn't implemented).
33 \wxheading{Available image handlers
}
35 The following image handlers are available.
{\bf wxBMPHandler
} is always
36 installed by default. To use other image formats, install the appropriate
37 handler with
\helpref{wxImage::AddHandler
}{wximageaddhandler
} or
38 \helpref{wxInitAllImageHandlers
}{wxinitallimagehandlers
}.
42 \twocolitem{\indexit{wxBMPHandler
}}{For loading and saving, always installed.
}
43 \twocolitem{\indexit{wxPNGHandler
}}{For loading (including alpha support) and saving.
}
44 \twocolitem{\indexit{wxJPEGHandler
}}{For loading and saving.
}
45 \twocolitem{\indexit{wxGIFHandler
}}{Only for loading, due to legal issues.
}
46 \twocolitem{\indexit{wxPCXHandler
}}{For loading and saving (see below).
}
47 \twocolitem{\indexit{wxPNMHandler
}}{For loading and saving (see below).
}
48 \twocolitem{\indexit{wxTIFFHandler
}}{For loading and saving.
}
49 \twocolitem{\indexit{wxIFFHandler
}}{For loading only.
}
50 \twocolitem{\indexit{wxXPMHandler
}}{For loading and saving.
}
51 \twocolitem{\indexit{wxICOHandler
}}{For loading and saving.
}
52 \twocolitem{\indexit{wxCURHandler
}}{For loading and saving.
}
53 \twocolitem{\indexit{wxANIHandler
}}{For loading only.
}
56 When saving in PCX format,
{\bf wxPCXHandler
} will count the number of
57 different colours in the image; if there are
256 or less colours, it will
58 save as
8 bit, else it will save as
24 bit.
60 Loading PNMs only works for ASCII or raw RGB images. When saving in
61 PNM format,
{\bf wxPNMHandler
} will always save as raw RGB.
63 \wxheading{Derived from
}
65 \helpref{wxObject
}{wxobject
}
67 \wxheading{Include files
}
73 \helpref{wxBitmap
}{wxbitmap
},
74 \helpref{wxInitAllImageHandlers
}{wxinitallimagehandlers
}
76 \latexignore{\rtfignore{\wxheading{Members
}}}
79 \membersection{wxImage::wxImage
}\label{wximagector
}
81 \func{}{wxImage
}{\void}
85 \func{}{wxImage
}{\param{const wxImage\&
}{image
}}
89 \func{}{wxImage
}{\param{const wxBitmap\&
}{ bitmap
}}
91 (Deprecated form, use
\helpref{wxBitmap::ConvertToImage
}{wxbitmapconverttoimage
}
92 instead.) Constructs an image from a platform-dependent bitmap. This preserves
93 mask information so that bitmaps and images can be converted back
94 and forth without loss in that respect.
96 \func{}{wxImage
}{\param{int
}{ width
},
\param{int
}{ height
},
\param{bool
}{ clear=true
}}
98 Creates an image with the given width and height. If
{\it clear
} is true, the new image will be initialized to black.
99 Otherwise, the image data will be uninitialized.
101 \func{}{wxImage
}{\param{int
}{ width
},
\param{int
}{ height
},
\param{unsigned char*
}{ data
},
\param{bool
}{ static
\_data=false
}}
103 Creates an image from given data with the given width and height. If
104 {\it static
\_data} is true, then wxImage will not delete the actual
105 image data in its destructor, otherwise it will free it by calling
108 \func{}{wxImage
}{\param{const wxString\&
}{name
},
\param{long
}{ type = wxBITMAP
\_TYPE\_ANY},
\param{int
}{ index = -
1}}
110 \func{}{wxImage
}{\param{const wxString\&
}{name
},
\param{const wxString\&
}{ mimetype
},
\param{int
}{ index = -
1}}
112 Loads an image from a file.
114 \func{}{wxImage
}{\param{wxInputStream\&
}{stream
},
\param{long
}{ type = wxBITMAP
\_TYPE\_ANY},
\param{int
}{ index = -
1}}
116 \func{}{wxImage
}{\param{wxInputStream\&
}{stream
},
\param{const wxString\&
}{ mimetype
},
\param{int
}{ index = -
1}}
118 Loads an image from an input stream.
120 \wxheading{Parameters
}
122 \docparam{width
}{Specifies the width of the image.
}
124 \docparam{height
}{Specifies the height of the image.
}
126 \docparam{name
}{Name of the file from which to load the image.
}
128 \docparam{stream
}{Opened input stream from which to load the image. Currently, the stream must support seeking.
}
130 \docparam{type
}{May be one of the following:
134 \twocolitem{\indexit{wxBITMAP
\_TYPE\_BMP}}{Load a Windows bitmap file.
}
135 \twocolitem{\indexit{wxBITMAP
\_TYPE\_GIF}}{Load a GIF bitmap file.
}
136 \twocolitem{\indexit{wxBITMAP
\_TYPE\_JPEG}}{Load a JPEG bitmap file.
}
137 \twocolitem{\indexit{wxBITMAP
\_TYPE\_PNG}}{Load a PNG bitmap file.
}
138 \twocolitem{\indexit{wxBITMAP
\_TYPE\_PCX}}{Load a PCX bitmap file.
}
139 \twocolitem{\indexit{wxBITMAP
\_TYPE\_PNM}}{Load a PNM bitmap file.
}
140 \twocolitem{\indexit{wxBITMAP
\_TYPE\_TIF}}{Load a TIFF bitmap file.
}
141 \twocolitem{\indexit{wxBITMAP
\_TYPE\_XPM}}{Load a XPM bitmap file.
}
142 \twocolitem{\indexit{wxBITMAP
\_TYPE\_ICO}}{Load a Windows icon file (ICO).
}
143 \twocolitem{\indexit{wxBITMAP
\_TYPE\_CUR}}{Load a Windows cursor file (CUR).
}
144 \twocolitem{\indexit{wxBITMAP
\_TYPE\_ANI}}{Load a Windows animated cursor file (ANI).
}
145 \twocolitem{\indexit{wxBITMAP
\_TYPE\_ANY}}{Will try to autodetect the format.
}
148 \docparam{mimetype
}{MIME type string (for example 'image/jpeg')
}
150 \docparam{index
}{Index of the image to load in the case that the image file contains multiple images.
151 This is only used by GIF, ICO and TIFF handlers. The default value (-
1) means
152 "choose the default image" and is interpreted as the first image (index=
0) by
153 the GIF and TIFF handler and as the largest and most colourful one by the ICO handler.
}
157 Depending on how wxWidgets has been configured, not all formats may be available.
159 Note: any handler other than BMP must be previously
160 initialized with
\helpref{wxImage::AddHandler
}{wximageaddhandler
} or
161 \helpref{wxInitAllImageHandlers
}{wxinitallimagehandlers
}.
163 Note: you can use
\helpref{GetOptionInt
}{wximagegetoptionint
} to get the
164 hotspot for loaded cursor file:
166 int hotspot_x = image.GetOptionInt(wxIMAGE_OPTION_CUR_HOTSPOT_X);
167 int hotspot_y = image.GetOptionInt(wxIMAGE_OPTION_CUR_HOTSPOT_Y);
173 \helpref{wxImage::LoadFile
}{wximageloadfile
}
175 \pythonnote{Constructors supported by wxPython are:
\par
176 \indented{2cm
}{\begin{twocollist
}
177 \twocolitem{{\bf wxImage(name, flag)
}}{Loads an image from a file
}
178 \twocolitem{{\bf wxNullImage()
}}{Create a null image (has no size or
180 \twocolitem{{\bf wxEmptyImage(width, height)
}}{Creates an empty image
182 \twocolitem{{\bf wxImageFromMime(name, mimetype
}}{Creates an image from
183 the given file of the given mimetype
}
184 \twocolitem{{\bf wxImageFromBitmap(bitmap)
}}{Creates an image from a
185 platform-dependent bitmap
}
189 \perlnote{Constructors supported by wxPerl are:
\par
191 \item{Wx::Image->new( bitmap )
}
192 \item{Wx::Image->new( icon )
}
193 \item{Wx::Image->new( width, height )
}
194 \item{Wx::Image->new( width, height, data )
}
195 \item{Wx::Image->new( file, type, index )
}
196 \item{Wx::Image->new( file, mimetype, index )
}
197 \item{Wx::Image->new( stream, type, index )
}
198 \item{Wx::Image->new( stream, mimetype, index )
}
203 \membersection{wxImage::
\destruct{wxImage
}}\label{wximagedtor
}
205 \func{}{\destruct{wxImage
}}{\void}
210 \membersection{wxImage::AddHandler
}\label{wximageaddhandler
}
212 \func{static void
}{AddHandler
}{\param{wxImageHandler*
}{ handler
}}
214 Adds a handler to the end of the static list of format handlers.
216 \docparam{handler
}{A new image format handler object. There is usually only one instance
217 of a given handler class in an application session.
}
221 \helpref{wxImageHandler
}{wximagehandler
}
223 \func{bool
}{CanRead
}{\param{const wxString\&
}{ filename
}}
225 returns true if the current image handlers can read this file
227 \pythonnote{In wxPython this static method is named
{\tt wxImage
\_AddHandler}.
}
229 \membersection{wxImage::CleanUpHandlers
}\label{wximagecleanuphandlers
}
231 \func{static void
}{CleanUpHandlers
}{\void}
233 Deletes all image handlers.
235 This function is called by wxWidgets on exit.
238 \membersection{wxImage::ComputeHistogram
}\label{wximagecomputehistogram
}
240 \constfunc{unsigned long
}{ComputeHistogram
}{\param{wxImageHistogram\&
}{histogram
}}
242 Computes the histogram of the image.
{\it histogram
} is a reference to
243 wxImageHistogram object. wxImageHistogram is a specialization of
244 \helpref{wxHashMap
}{wxhashmap
} "template" and is defined as follows:
247 class WXDLLEXPORT wxImageHistogramEntry
250 wxImageHistogramEntry() : index(
0), value(
0)
{}
255 WX_DECLARE_EXPORTED_HASH_MAP(unsigned long, wxImageHistogramEntry,
256 wxIntegerHash, wxIntegerEqual,
260 \wxheading{Return value
}
262 Returns number of colours in the histogram.
265 \membersection{wxImage::ConvertAlphaToMask
}\label{wximageconvertalphatomask
}
267 \func{bool
}{ConvertAlphaToMask
}{\param{unsigned char
}{ threshold =
128}}
269 If the image has alpha channel, this method converts it to mask. All pixels
270 with alpha value less than
\arg{threshold
} are replaced with mask colour
271 and the alpha channel is removed. Mask colour is chosen automatically using
272 \helpref{FindFirstUnusedColour
}{wximagefindfirstunusedcolour
}.
274 If the image image doesn't have alpha channel,
275 ConvertAlphaToMask does nothing.
277 \wxheading{Return value
}
279 \false if FindFirstUnusedColour returns
\false,
\true otherwise.
282 \membersection{wxImage::ConvertToBitmap
}\label{wximageconverttobitmap
}
284 \constfunc{wxBitmap
}{ConvertToBitmap
}{\void}
286 Deprecated, use equivalent
\helpref{wxBitmap constructor
}{wxbitmapctor
}
287 (which takes wxImage and depth as its arguments) instead.
290 \membersection{wxImage::ConvertToMono
}\label{wxbitmapconverttomono
}
292 \constfunc{wxImage
}{ConvertToMono
}{\param{unsigned char
}{ r
},
\param{unsigned char
}{ g
},
\param{unsigned char
}{ b
}}
294 Returns monochromatic version of the image. The returned image has white
295 colour where the original has
{\it (r,g,b)
} colour and black colour
299 \membersection{wxImage::Copy
}\label{wximagecopy
}
301 \constfunc{wxImage
}{Copy
}{\void}
303 Returns an identical copy of the image.
306 \membersection{wxImage::Create
}\label{wximagecreate
}
308 \func{bool
}{Create
}{\param{int
}{ width
},
\param{int
}{ height
},
\param{bool
}{ clear=true
}}
310 Creates a fresh image. If
{\it clear
} is true, the new image will be initialized to black.
311 Otherwise, the image data will be uninitialized.
313 \wxheading{Parameters
}
315 \docparam{width
}{The width of the image in pixels.
}
317 \docparam{height
}{The height of the image in pixels.
}
319 \wxheading{Return value
}
321 true if the call succeeded, false otherwise.
324 \membersection{wxImage::Destroy
}\label{wximagedestroy
}
326 \func{void
}{Destroy
}{\void}
328 Destroys the image data.
331 \membersection{wxImage::FindFirstUnusedColour
}\label{wximagefindfirstunusedcolour
}
333 \func{bool
}{FindFirstUnusedColour
}{\param{unsigned char *
}{ r
},
\param{unsigned char *
}{ g
},
\param{unsigned char *
}{ b
},
\param{unsigned char
}{ startR =
1},
\param{unsigned char
}{ startG =
0},
\param{unsigned char
}{ startB =
0}}
335 \wxheading{Parameters
}
337 \docparam{r,g,b
}{Pointers to variables to save the colour.
}
339 \docparam{startR,startG,startB
}{Initial values of the colour. Returned colour
340 will have RGB values equal to or greater than these.
}
342 Finds the first colour that is never used in the image. The search begins at
343 given initial colour and continues by increasing R, G and B components (in this
344 order) by
1 until an unused colour is found or the colour space exhausted.
346 \wxheading{Return value
}
348 Returns false if there is no unused colour left, true on success.
352 Note that this method involves computing the histogram, which is
353 computationally intensive operation.
356 \membersection{wxImage::FindHandler
}\label{wximagefindhandler
}
358 \func{static wxImageHandler*
}{FindHandler
}{\param{const wxString\&
}{name
}}
360 Finds the handler with the given name.
362 \func{static wxImageHandler*
}{FindHandler
}{\param{const wxString\&
}{extension
},
\param{long
}{ imageType
}}
364 Finds the handler associated with the given extension and type.
366 \func{static wxImageHandler*
}{FindHandler
}{\param{long
}{imageType
}}
368 Finds the handler associated with the given image type.
370 \func{static wxImageHandler*
}{FindHandlerMime
}{\param{const wxString\&
}{mimetype
}}
372 Finds the handler associated with the given MIME type.
374 \docparam{name
}{The handler name.
}
376 \docparam{extension
}{The file extension, such as ``bmp".
}
378 \docparam{imageType
}{The image type, such as wxBITMAP
\_TYPE\_BMP.
}
380 \docparam{mimetype
}{MIME type.
}
382 \wxheading{Return value
}
384 A pointer to the handler if found, NULL otherwise.
388 \helpref{wxImageHandler
}{wximagehandler
}
391 \membersection{wxImage::GetImageExtWildcard
}\label{wximagegetimageextwildcard
}
393 \func{static wxString
}{GetImageExtWildcard
}{\void}
395 Iterates all registered wxImageHandler objects, and returns a string containing file extension masks
396 suitable for passing to file open/save dialog boxes.
398 \wxheading{Return value
}
400 The format of the returned string is "
(*.ext1;*.ext2)|*.ext1;*.ext2".
402 It is usually a good idea to prepend a description before passing the result to the dialog.
407 wxFileDialog FileDlg( this, "Choose Image", ::wxGetWorkingDirectory(), "", _("Image Files ") + wxImage::GetImageExtWildcard(), wxOPEN );
412 \helpref{wxImageHandler}{wximagehandler}
415 \membersection{wxImage::GetAlpha}\label{wximagegetalpha}
417 \constfunc{unsigned char}{GetAlpha}{\param{int}{ x}, \param{int}{ y}}
419 Returns the alpha value for the given pixel. This function may only be called
420 for the images with alpha channel, use \helpref{HasAlpha}{wximagehasalpha} to
423 The returned value is the {\it opacity} of the image, i.e. the value of $0$
424 corresponds to the transparent pixels while the value of $255$ -- to the opaque
427 \constfunc{unsigned char *}{GetAlpha}{\void}
429 Returns pointer to the array storing the alpha values for this image. This
430 pointer is {\tt NULL} for the images without the alpha channel. If the image
431 does have it, this pointer may be used to directly manipulate the alpha values
432 which are stored as the \helpref{RGB}{wximagegetdata} ones.
435 \membersection{wxImage::GetBlue}\label{wximagegetblue}
437 \constfunc{unsigned char}{GetBlue}{\param{int}{ x}, \param{int}{ y}}
439 Returns the blue intensity at the given coordinate.
442 \membersection{wxImage::GetData}\label{wximagegetdata}
444 \constfunc{unsigned char*}{GetData}{\void}
446 Returns the image data as an array. This is most often used when doing
447 direct image manipulation. The return value points to an array of
448 characters in RGBRGBRGB$\ldots$ format in the top-to-bottom, left-to-right
449 order, that is the first RGB triplet corresponds to the pixel first pixel of
450 the first row, the second one --- to the second pixel of the first row and so
451 on until the end of the first row, with second row following after it and so
454 You should not delete the returned pointer nor pass it to
455 \helpref{wxImage::SetData}{wximagesetdata}.
458 \membersection{wxImage::GetGreen}\label{wximagegetgreen}
460 \constfunc{unsigned char}{GetGreen}{\param{int}{ x}, \param{int}{ y}}
462 Returns the green intensity at the given coordinate.
465 \membersection{wxImage::GetImageCount}\label{wximagegetimagecount}
467 \func{static int}{GetImageCount}{\param{const wxString\&}{ filename}, \param{long}{ type = wxBITMAP\_TYPE\_ANY}}
469 \func{static int}{GetImageCount}{\param{wxInputStream\&}{ stream}, \param{long}{ type = wxBITMAP\_TYPE\_ANY}}
471 If the image file contains more than one image and the image handler is capable
472 of retrieving these individually, this function will return the number of
475 \docparam{name}{Name of the file to query.}
477 \docparam{stream}{Opened input stream with image data. Currently, the stream must support seeking.}
479 \docparam{type}{May be one of the following:
483 \twocolitem{\indexit{wxBITMAP\_TYPE\_BMP}}{Load a Windows bitmap file.}
484 \twocolitem{\indexit{wxBITMAP\_TYPE\_GIF}}{Load a GIF bitmap file.}
485 \twocolitem{\indexit{wxBITMAP\_TYPE\_JPEG}}{Load a JPEG bitmap file.}
486 \twocolitem{\indexit{wxBITMAP\_TYPE\_PNG}}{Load a PNG bitmap file.}
487 \twocolitem{\indexit{wxBITMAP\_TYPE\_PCX}}{Load a PCX bitmap file.}
488 \twocolitem{\indexit{wxBITMAP\_TYPE\_PNM}}{Load a PNM bitmap file.}
489 \twocolitem{\indexit{wxBITMAP\_TYPE\_TIF}}{Load a TIFF bitmap file.}
490 \twocolitem{\indexit{wxBITMAP\_TYPE\_XPM}}{Load a XPM bitmap file.}
491 \twocolitem{\indexit{wxBITMAP\_TYPE\_ICO}}{Load a Windows icon file (ICO).}
492 \twocolitem{\indexit{wxBITMAP\_TYPE\_CUR}}{Load a Windows cursor file (CUR).}
493 \twocolitem{\indexit{wxBITMAP\_TYPE\_ANI}}{Load a Windows animated cursor file (ANI).}
494 \twocolitem{\indexit{wxBITMAP\_TYPE\_ANY}}{Will try to autodetect the format.}
497 \wxheading{Return value}
499 Number of available images. For most image handlers, this is 1 (exceptions
500 are TIFF and ICO formats).
503 \membersection{wxImage::GetHandlers}\label{wximagegethandlers}
505 \func{static wxList\&}{GetHandlers}{\void}
507 Returns the static list of image format handlers.
511 \helpref{wxImageHandler}{wximagehandler}
514 \membersection{wxImage::GetHeight}\label{wximagegetheight}
516 \constfunc{int}{GetHeight}{\void}
518 Gets the height of the image in pixels.
521 \membersection{wxImage::GetMaskBlue}\label{wximagegetmaskblue}
523 \constfunc{unsigned char}{GetMaskBlue}{\void}
525 Gets the blue value of the mask colour.
528 \membersection{wxImage::GetMaskGreen}\label{wximagegetmaskgreen}
530 \constfunc{unsigned char}{GetMaskGreen}{\void}
532 Gets the green value of the mask colour.
535 \membersection{wxImage::GetMaskRed}\label{wximagegetmaskred}
537 \constfunc{unsigned char}{GetMaskRed}{\void}
539 Gets the red value of the mask colour.
542 \membersection{wxImage::GetPalette}\label{wximagegetpalette}
544 \constfunc{const wxPalette\&}{GetPalette}{\void}
546 Returns the palette associated with the image. Currently the palette is only
547 used when converting to wxBitmap under Windows.
549 Eventually wxImage handlers will set the palette if one exists in the image file.
552 \membersection{wxImage::GetRed}\label{wximagegetred}
554 \constfunc{unsigned char}{GetRed}{\param{int}{ x}, \param{int}{ y}}
556 Returns the red intensity at the given coordinate.
559 \membersection{wxImage::GetSubImage}\label{wximagegetsubimage}
561 \constfunc{wxImage}{GetSubImage}{\param{const wxRect\&}{ rect}}
563 Returns a sub image of the current one as long as the rect belongs entirely to
567 \membersection{wxImage::GetWidth}\label{wximagegetwidth}
569 \constfunc{int}{GetWidth}{\void}
571 Gets the width of the image in pixels.
575 \helpref{wxImage::GetHeight}{wximagegetheight}
578 \membersection{wxImage::HasAlpha}\label{wximagehasalpha}
580 \constfunc{bool}{HasAlpha}{\void}
582 Returns true if this image has alpha channel, false otherwise.
586 \helpref{GetAlpha}{wximagegetalpha}, \helpref{SetAlpha}{wximagesetalpha}
589 \membersection{wxImage::HasMask}\label{wximagehasmask}
591 \constfunc{bool}{HasMask}{\void}
593 Returns true if there is a mask active, false otherwise.
596 \membersection{wxImage::GetOption}\label{wximagegetoption}
598 \constfunc{wxString}{GetOption}{\param{const wxString\&}{ name}}
600 Gets a user-defined option. The function is case-insensitive to {\it name}.
602 For example, when saving as a JPEG file, the option {\bf quality} is
603 used, which is a number between 0 and 100 (0 is terrible, 100 is very good).
607 \helpref{wxImage::SetOption}{wximagesetoption},\rtfsp
608 \helpref{wxImage::GetOptionInt}{wximagegetoptionint},\rtfsp
609 \helpref{wxImage::HasOption}{wximagehasoption}
612 \membersection{wxImage::GetOptionInt}\label{wximagegetoptionint}
614 \constfunc{int}{GetOptionInt}{\param{const wxString\&}{ name}}
616 Gets a user-defined option as an integer. The function is case-insensitive to {\it name}.
618 If the given option is not present, the function returns $0$. Use
619 \helpref{wxImage::HasOption}{wximagehasoption} is $0$ is a possibly valid value
622 Options for wxPNGHandler
625 \twocolitem{wxIMAGE\_OPTION\_PNG\_FORMAT}{Format for saving a PNG file.}
626 \twocolitem{wxIMAGE\_OPTION\_PNG\_BITDEPTH}{Bit depth for every channel (R/G/B/A).}
629 Supported values for wxIMAGE\_OPTION\_PNG\_FORMAT:
632 \twocolitem{wxPNG\_TYPE\_COLOUR}{Stores RGB image.}
633 \twocolitem{wxPNG\_TYPE\_GREY}{Stores grey image, converts from RGB.}
634 \twocolitem{wxPNG\_TYPE\_GREY\_RED}{Stores grey image, uses red value as grey.}
640 \helpref{wxImage::SetOption}{wximagesetoption},\rtfsp
641 \helpref{wxImage::GetOption}{wximagegetoption}
644 \membersection{wxImage::HasOption}\label{wximagehasoption}
646 \constfunc{bool}{HasOption}{\param{const wxString\&}{ name}}
648 Returns true if the given option is present. The function is case-insensitive to {\it name}.
652 \helpref{wxImage::SetOption}{wximagesetoption},\rtfsp
653 \helpref{wxImage::GetOption}{wximagegetoption},\rtfsp
654 \helpref{wxImage::GetOptionInt}{wximagegetoptionint}
657 \membersection{wxImage::InitAlpha}\label{wximageinitalpha}
659 \func{void}{InitAlpha}{\void}
661 Initializes the image alpha channel data. It is an error to call it
662 if the image already has alpha data. If it doesn't, alpha data will be
663 by default initialized to all pixels being fully opaque. But if the image has a
664 a mask colour, all mask pixels will be completely transparent.
667 \membersection{wxImage::InitStandardHandlers}\label{wximageinitstandardhandlers}
669 \func{static void}{InitStandardHandlers}{\void}
671 Internal use only. Adds standard image format handlers. It only install BMP
672 for the time being, which is used by wxBitmap.
674 This function is called by wxWidgets on startup, and shouldn't be called by
679 \helpref{wxImageHandler}{wximagehandler},
680 \helpref{wxInitAllImageHandlers}{wxinitallimagehandlers}
683 \membersection{wxImage::InsertHandler}\label{wximageinserthandler}
685 \func{static void}{InsertHandler}{\param{wxImageHandler*}{ handler}}
687 Adds a handler at the start of the static list of format handlers.
689 \docparam{handler}{A new image format handler object. There is usually only one instance
690 of a given handler class in an application session.}
694 \helpref{wxImageHandler}{wximagehandler}
697 \membersection{wxImage::LoadFile}\label{wximageloadfile}
699 \func{bool}{LoadFile}{\param{const wxString\&}{ name}, \param{long}{ type = wxBITMAP\_TYPE\_ANY}, \param{int}{ index = -1}}
701 \func{bool}{LoadFile}{\param{const wxString\&}{ name}, \param{const wxString\&}{ mimetype}, \param{int}{ index = -1}}
703 Loads an image from a file. If no handler type is provided, the library will
704 try to autodetect the format.
706 \func{bool}{LoadFile}{\param{wxInputStream\&}{ stream}, \param{long}{ type}, \param{int}{ index = -1}}
708 \func{bool}{LoadFile}{\param{wxInputStream\&}{ stream}, \param{const wxString\&}{ mimetype}, \param{int}{ index = -1}}
710 Loads an image from an input stream.
712 \wxheading{Parameters}
714 \docparam{name}{Name of the file from which to load the image.}
716 \docparam{stream}{Opened input stream from which to load the image. Currently, the stream must support seeking.}
718 \docparam{type}{One of the following values:
722 \twocolitem{{\bf wxBITMAP\_TYPE\_BMP}}{Load a Windows image file.}
723 \twocolitem{{\bf wxBITMAP\_TYPE\_GIF}}{Load a GIF image file.}
724 \twocolitem{{\bf wxBITMAP\_TYPE\_JPEG}}{Load a JPEG image file.}
725 \twocolitem{{\bf wxBITMAP\_TYPE\_PCX}}{Load a PCX image file.}
726 \twocolitem{{\bf wxBITMAP\_TYPE\_PNG}}{Load a PNG image file.}
727 \twocolitem{{\bf wxBITMAP\_TYPE\_PNM}}{Load a PNM image file.}
728 \twocolitem{{\bf wxBITMAP\_TYPE\_TIF}}{Load a TIFF image file.}
729 \twocolitem{{\bf wxBITMAP\_TYPE\_XPM}}{Load a XPM image file.}
730 \twocolitem{{\bf wxBITMAP\_TYPE\_ICO}}{Load a Windows icon file (ICO).}
731 \twocolitem{{\bf wxBITMAP\_TYPE\_CUR}}{Load a Windows cursor file (CUR).}
732 \twocolitem{\indexit{wxBITMAP\_TYPE\_ANI}}{Load a Windows animated cursor file (ANI).}
733 \twocolitem{{\bf wxBITMAP\_TYPE\_ANY}}{Will try to autodetect the format.}
736 \docparam{mimetype}{MIME type string (for example 'image/jpeg')}
738 \docparam{index}{Index of the image to load in the case that the image file contains multiple images.
739 This is only used by GIF, ICO and TIFF handlers. The default value (-1) means
740 "choose the default image" and is interpreted as the first image (index=0) by
741 the GIF and TIFF handler and as the largest and most colourful one by the ICO handler.}
745 Depending on how wxWidgets has been configured, not all formats may be available.
747 Note: you can use \helpref{GetOptionInt}{wximagegetoptionint} to get the
748 hotspot for loaded cursor file:
750 int hotspot_x = image.GetOptionInt(wxIMAGE_OPTION_CUR_HOTSPOT_X);
751 int hotspot_y = image.GetOptionInt(wxIMAGE_OPTION_CUR_HOTSPOT_Y);
755 \wxheading{Return value}
757 true if the operation succeeded, false otherwise. If the optional index parameter is out of range,
758 false is returned and a call to wxLogError() takes place.
762 \helpref{wxImage::SaveFile}{wximagesavefile}
764 \pythonnote{In place of a single overloaded method name, wxPython
765 implements the following methods:\par
766 \indented{2cm}{\begin{twocollist}
767 \twocolitem{{\bf LoadFile(filename, type)}}{Loads an image of the given
769 \twocolitem{{\bf LoadMimeFile(filename, mimetype)}}{Loads an image of the given
770 mimetype from a file}
774 \perlnote{Methods supported by wxPerl are:\par
776 \item{bitmap->LoadFile( name, type )}
777 \item{bitmap->LoadFile( name, mimetype )}
783 \membersection{wxImage::Ok}\label{wximageok}
785 \constfunc{bool}{Ok}{\void}
787 Returns true if image data is present.
790 \membersection{wxImage::RemoveHandler}\label{wximageremovehandler}
792 \func{static bool}{RemoveHandler}{\param{const wxString\& }{name}}
794 Finds the handler with the given name, and removes it. The handler
797 \docparam{name}{The handler name.}
799 \wxheading{Return value}
801 true if the handler was found and removed, false otherwise.
805 \helpref{wxImageHandler}{wximagehandler}
808 \membersection{wxImage::Mirror}\label{wximagemirror}
810 \constfunc{wxImage}{Mirror}{\param{bool}{ horizontally = true}}
812 Returns a mirrored copy of the image. The parameter {\it horizontally}
813 indicates the orientation.
816 \membersection{wxImage::Replace}\label{wximagereplace}
818 \func{void}{Replace}{\param{unsigned char}{ r1}, \param{unsigned char}{ g1}, \param{unsigned char}{ b1},
819 \param{unsigned char}{ r2}, \param{unsigned char}{ g2}, \param{unsigned char}{ b2}}
821 Replaces the colour specified by {\it r1,g1,b1} by the colour {\it r2,g2,b2}.
824 \membersection{wxImage::Rescale}\label{wximagerescale}
826 \func{wxImage \&}{Rescale}{\param{int}{ width}, \param{int}{ height}}
828 Changes the size of the image in-place: after a call to this function, the
829 image will have the given width and height.
831 Returns the (modified) image itself.
835 \helpref{Scale}{wximagescale}
838 \membersection{wxImage::Rotate}\label{wximagerotate}
840 \func{wxImage}{Rotate}{\param{double}{ angle}, \param{const wxPoint\& }{rotationCentre},
841 \param{bool}{ interpolating = true}, \param{wxPoint*}{ offsetAfterRotation = NULL}}
843 Rotates the image about the given point, by {\it angle} radians. Passing true
844 to {\it interpolating} results in better image quality, but is slower. If the
845 image has a mask, then the mask colour is used for the uncovered pixels in the
846 rotated image background. Else, black (rgb 0, 0, 0) will be used.
848 Returns the rotated image, leaving this image intact.
851 \membersection{wxImage::Rotate90}\label{wximagerotate90}
853 \constfunc{wxImage}{Rotate90}{\param{bool}{ clockwise = true}}
855 Returns a copy of the image rotated 90 degrees in the direction
856 indicated by {\it clockwise}.
859 \membersection{wxImage::SaveFile}\label{wximagesavefile}
861 \constfunc{bool}{SaveFile}{\param{const wxString\& }{name}, \param{int}{ type}}
863 \constfunc{bool}{SaveFile}{\param{const wxString\& }{name}, \param{const wxString\&}{ mimetype}}
865 Saves an image in the named file.
867 \constfunc{bool}{SaveFile}{\param{const wxString\& }{name}}
869 Saves an image in the named file. File type is determined from the extension of the
870 file name. Note that this function may fail if the extension is not recognized! You
871 can use one of the forms above to save images to files with non-standard extensions.
873 \constfunc{bool}{SaveFile}{\param{wxOutputStream\& }{stream}, \param{int}{ type}}
875 \constfunc{bool}{SaveFile}{\param{wxOutputStream\& }{stream}, \param{const wxString\&}{ mimetype}}
877 Saves an image in the given stream.
879 \wxheading{Parameters}
881 \docparam{name}{Name of the file to save the image to.}
883 \docparam{stream}{Opened output stream to save the image to.}
885 \docparam{type}{Currently these types can be used:
889 \twocolitem{{\bf wxBITMAP\_TYPE\_BMP}}{Save a BMP image file.}
890 \twocolitem{{\bf wxBITMAP\_TYPE\_JPEG}}{Save a JPEG image file.}
891 \twocolitem{{\bf wxBITMAP\_TYPE\_PNG}}{Save a PNG image file.}
892 \twocolitem{{\bf wxBITMAP\_TYPE\_PCX}}{Save a PCX image file (tries to save as 8-bit if possible, falls back to 24-bit otherwise).}
893 \twocolitem{{\bf wxBITMAP\_TYPE\_PNM}}{Save a PNM image file (as raw RGB always).}
894 \twocolitem{{\bf wxBITMAP\_TYPE\_TIFF}}{Save a TIFF image file.}
895 \twocolitem{{\bf wxBITMAP\_TYPE\_XPM}}{Save a XPM image file.}
896 \twocolitem{{\bf wxBITMAP\_TYPE\_ICO}}{Save a Windows icon file (ICO) (the size may be up to 255 wide by 127 high. A single image is saved in 8 colors at the size supplied).}
897 \twocolitem{{\bf wxBITMAP\_TYPE\_CUR}}{Save a Windows cursor file (CUR).}
900 \docparam{mimetype}{MIME type.}
902 \wxheading{Return value}
904 true if the operation succeeded, false otherwise.
908 Depending on how wxWidgets has been configured, not all formats may be available.
910 Note: you can use \helpref{GetOptionInt}{wximagegetoptionint} to set the
911 hotspot before saving an image into a cursor file (default hotspot is in
912 the centre of the image):
914 image.SetOption(wxIMAGE_OPTION_CUR_HOTSPOT_X, hotspotX);
915 image.SetOption(wxIMAGE_OPTION_CUR_HOTSPOT_Y, hotspotY);
921 \helpref{wxImage::LoadFile}{wximageloadfile}
923 \pythonnote{In place of a single overloaded method name, wxPython
924 implements the following methods:\par
925 \indented{2cm}{\begin{twocollist}
926 \twocolitem{{\bf SaveFile(filename, type)}}{Saves the image using the given
927 type to the named file}
928 \twocolitem{{\bf SaveMimeFile(filename, mimetype)}}{Saves the image using the given
929 mimetype to the named file}
933 \perlnote{Methods supported by wxPerl are:\par
935 \item{bitmap->SaveFile( name, type )}
936 \item{bitmap->SaveFile( name, mimetype )}
941 \membersection{wxImage::Scale}\label{wximagescale}
943 \constfunc{wxImage}{Scale}{\param{int}{ width}, \param{int}{ height}}
945 Returns a scaled version of the image. This is also useful for
946 scaling bitmaps in general as the only other way to scale bitmaps
947 is to blit a wxMemoryDC into another wxMemoryDC.
949 It may be mentioned that the GTK port uses this function internally
950 to scale bitmaps when using mapping modes in wxDC.
955 // get the bitmap from somewhere
958 // rescale it to have size of 32*32
959 if ( bmp.GetWidth() != 32 || bmp.GetHeight() != 32 )
961 wxImage image = bmp.ConvertToImage();
962 bmp = wxBitmap(image.Scale(32, 32));
964 // another possibility:
965 image.Rescale(32, 32);
973 \helpref{Rescale}{wximagerescale}
976 \membersection{wxImage::SetAlpha}\label{wximagesetalpha}
978 \func{void}{SetAlpha}{\param{unsigned char *}{alpha = {\tt NULL}}}
980 This function is similar to \helpref{SetData}{wximagesetdata} and has similar
981 restrictions. The pointer passed to it may however be {\tt NULL} in which case
982 the function will allocate the alpha array internally -- this is useful to add
983 alpha channel data to an image which doesn't have any. If the pointer is not
984 {\tt NULL}, it must have one byte for each image pixel and be allocated with
985 {\tt malloc()}. wxImage takes ownership of the pointer and will free it.
987 \func{void}{SetAlpha}{\param{int }{x}, \param{int }{y}, \param{unsigned char }{alpha}}
989 Sets the alpha value for the given pixel. This function should only be called
990 if the image has alpha channel data, use \helpref{HasAlpha}{wximagehasalpha} to
994 \membersection{wxImage::SetData}\label{wximagesetdata}
996 \func{void}{SetData}{\param{unsigned char*}{data}}
998 Sets the image data without performing checks. The data given must have
999 the size (width*height*3) or results will be unexpected. Don't use this
1000 method if you aren't sure you know what you are doing.
1002 The data must have been allocated with {\tt malloc()}, {\large {\bf NOT}} with
1005 After this call the pointer to the data is owned by the wxImage object,
1006 that will be responsible for deleting it.
1007 Do not pass to this function a pointer obtained through
1008 \helpref{wxImage::GetData}{wximagegetdata}.
1011 \membersection{wxImage::SetMask}\label{wximagesetmask}
1013 \func{void}{SetMask}{\param{bool}{ hasMask = true}}
1015 Specifies whether there is a mask or not. The area of the mask is determined by the current mask colour.
1018 \membersection{wxImage::SetMaskColour}\label{wximagesetmaskcolour}
1020 \func{void}{SetMaskColour}{\param{unsigned char }{red}, \param{unsigned char }{green}, \param{unsigned char }{blue}}
1022 Sets the mask colour for this image (and tells the image to use the mask).
1025 \membersection{wxImage::SetMaskFromImage}\label{wximagesetmaskfromimage}
1027 \func{bool}{SetMaskFromImage}{\param{const wxImage\&}{ mask}, \param{unsigned char}{ mr}, \param{unsigned char}{ mg}, \param{unsigned char}{ mb}}
1029 \wxheading{Parameters}
1031 \docparam{mask}{The mask image to extract mask shape from. Must have same dimensions as the image.}
1033 \docparam{mr,mg,mb}{RGB value of pixels in {\it mask} that will be used to create the mask.}
1035 Sets image's mask so that the pixels that have RGB value of {\it mr,mg,mb}
1036 in {\it mask} will be masked in the image. This is done by first finding an
1037 unused colour in the image, setting this colour as the mask colour and then
1038 using this colour to draw all pixels in the image who corresponding pixel
1039 in {\it mask} has given RGB value.
1041 \wxheading{Return value}
1043 Returns false if {\it mask} does not have same dimensions as the image or if
1044 there is no unused colour left. Returns true if the mask was successfully
1049 Note that this method involves computing the histogram, which is
1050 computationally intensive operation.
1053 \membersection{wxImage::SetOption}\label{wximagesetoption}
1055 \func{void}{SetOption}{\param{const wxString\&}{ name}, \param{const wxString\&}{ value}}
1057 \func{void}{SetOption}{\param{const wxString\&}{ name}, \param{int}{ value}}
1059 Sets a user-defined option. The function is case-insensitive to {\it name}.
1061 For example, when saving as a JPEG file, the option {\bf quality} is
1062 used, which is a number between 0 and 100 (0 is terrible, 100 is very good).
1064 \wxheading{See also}
1066 \helpref{wxImage::GetOption}{wximagegetoption},\rtfsp
1067 \helpref{wxImage::GetOptionInt}{wximagegetoptionint},\rtfsp
1068 \helpref{wxImage::HasOption}{wximagehasoption}
1071 \membersection{wxImage::SetPalette}\label{wximagesetpalette}
1073 \func{void}{SetPalette}{\param{const wxPalette\&}{ palette}}
1075 Associates a palette with the image. The palette may be used when converting
1076 wxImage to wxBitmap (MSW only at present) or in file save operations (none as yet).
1079 \membersection{wxImage::SetRGB}\label{wximagesetrgb}
1081 \func{void}{SetRGB}{\param{int }{x}, \param{int }{y}, \param{unsigned char }{red}, \param{unsigned char }{green}, \param{unsigned char }{blue}}
1083 Sets the pixel at the given coordinate. This routine performs bounds-checks
1084 for the coordinate so it can be considered a safe way to manipulate the
1085 data, but in some cases this might be too slow so that the data will have to
1086 be set directly. In that case you will have to get access to the image data
1087 using the \helpref{GetData}{wximagegetdata} method.
1090 \membersection{wxImage::operator $=$}\label{wximageassign}
1092 \func{wxImage\& }{operator $=$}{\param{const wxImage\& }{image}}
1094 Assignment operator. This operator does not copy any data, but instead
1095 passes a pointer to the data in {\it image} and increments a reference
1096 counter. It is a fast operation.
1098 \wxheading{Parameters}
1100 \docparam{image}{Image to assign.}
1102 \wxheading{Return value}
1104 Returns 'this' object.
1107 \membersection{wxImage::operator $==$}\label{wximageequal}
1109 \constfunc{bool}{operator $==$}{\param{const wxImage\& }{image}}
1111 Equality operator. This operator tests whether the internal data pointers are
1112 equal (a fast test).
1114 \wxheading{Parameters}
1116 \docparam{image}{Image to compare with 'this'}
1118 \wxheading{Return value}
1120 Returns true if the images were effectively equal, false otherwise.
1123 \membersection{wxImage::operator $!=$}\label{wximagenotequal}
1125 \constfunc{bool}{operator $!=$}{\param{const wxImage\& }{image}}
1127 Inequality operator. This operator tests whether the internal data pointers are
1128 unequal (a fast test).
1130 \wxheading{Parameters}
1132 \docparam{image}{Image to compare with 'this'}
1134 \wxheading{Return value}
1136 Returns true if the images were unequal, false otherwise.
1138 \section{\class{wxImageHandler}}\label{wximagehandler}
1140 This is the base class for implementing image file loading/saving, and image creation from data.
1141 It is used within wxImage and is not normally seen by the application.
1143 If you wish to extend the capabilities of wxImage, derive a class from wxImageHandler
1144 and add the handler using \helpref{wxImage::AddHandler}{wximageaddhandler} in your
1145 application initialisation.
1147 \wxheading{Note (Legal Issue)}
1149 This software is based in part on the work of the Independent JPEG Group.
1151 (Applies when wxWidgets is linked with JPEG support. wxJPEGHandler uses libjpeg
1154 \wxheading{Derived from}
1156 \helpref{wxObject}{wxobject}
1158 \wxheading{Include files}
1162 \wxheading{See also}
1164 \helpref{wxImage}{wximage},
1165 \helpref{wxInitAllImageHandlers}{wxinitallimagehandlers}
1167 \latexignore{\rtfignore{\wxheading{Members}}}
1170 \membersection{wxImageHandler::wxImageHandler}\label{wximagehandlerctor}
1172 \func{}{wxImageHandler}{\void}
1174 Default constructor. In your own default constructor, initialise the members
1175 m\_name, m\_extension and m\_type.
1178 \membersection{wxImageHandler::\destruct{wxImageHandler}}\label{wximagehandlerdtor}
1180 \func{}{\destruct{wxImageHandler}}{\void}
1182 Destroys the wxImageHandler object.
1185 \membersection{wxImageHandler::GetName}\label{wximagehandlergetname}
1187 \constfunc{wxString}{GetName}{\void}
1189 Gets the name of this handler.
1192 \membersection{wxImageHandler::GetExtension}\label{wximagehandlergetextension}
1194 \constfunc{wxString}{GetExtension}{\void}
1196 Gets the file extension associated with this handler.
1199 \membersection{wxImageHandler::GetImageCount}\label{wximagehandlergetimagecount}
1201 \func{int}{GetImageCount}{\param{wxInputStream\&}{ stream}}
1203 If the image file contains more than one image and the image handler is capable
1204 of retrieving these individually, this function will return the number of
1207 \docparam{stream}{Opened input stream for reading image data. Currently, the stream must support seeking.}
1209 \wxheading{Return value}
1211 Number of available images. For most image handlers, this is 1 (exceptions
1212 are TIFF and ICO formats).
1215 \membersection{wxImageHandler::GetType}\label{wximagehandlergettype}
1217 \constfunc{long}{GetType}{\void}
1219 Gets the image type associated with this handler.
1222 \membersection{wxImageHandler::GetMimeType}\label{wximagehandlergetmimetype}
1224 \constfunc{wxString}{GetMimeType}{\void}
1226 Gets the MIME type associated with this handler.
1229 \membersection{wxImageHandler::LoadFile}\label{wximagehandlerloadfile}
1231 \func{bool}{LoadFile}{\param{wxImage* }{image}, \param{wxInputStream\&}{ stream}, \param{bool}{ verbose=true}, \param{int}{ index=0}}
1233 Loads a image from a stream, putting the resulting data into {\it image}. If the image file contains
1234 more than one image and the image handler is capable of retrieving these individually, {\it index}
1235 indicates which image to read from the stream.
1237 \wxheading{Parameters}
1239 \docparam{image}{The image object which is to be affected by this operation.}
1241 \docparam{stream}{Opened input stream for reading image data.}
1243 \docparam{verbose}{If set to true, errors reported by the image handler will produce wxLogMessages.}
1245 \docparam{index}{The index of the image in the file (starting from zero).}
1247 \wxheading{Return value}
1249 true if the operation succeeded, false otherwise.
1251 \wxheading{See also}
1253 \helpref{wxImage::LoadFile}{wximageloadfile},
1254 \helpref{wxImage::SaveFile}{wximagesavefile},
1255 \helpref{wxImageHandler::SaveFile}{wximagehandlersavefile}
1258 \membersection{wxImageHandler::SaveFile}\label{wximagehandlersavefile}
1260 \func{bool}{SaveFile}{\param{wxImage* }{image}, \param{wxOutputStream\& }{stream}}
1262 Saves a image in the output stream.
1264 \wxheading{Parameters}
1266 \docparam{image}{The image object which is to be affected by this operation.}
1268 \docparam{stream}{Opened output stream for writing the data.}
1270 \wxheading{Return value}
1272 true if the operation succeeded, false otherwise.
1274 \wxheading{See also}
1276 \helpref{wxImage::LoadFile}{wximageloadfile},
1277 \helpref{wxImage::SaveFile}{wximagesavefile},
1278 \helpref{wxImageHandler::LoadFile}{wximagehandlerloadfile}
1281 \membersection{wxImageHandler::SetName}\label{wximagehandlersetname}
1283 \func{void}{SetName}{\param{const wxString\& }{name}}
1285 Sets the handler name.
1287 \wxheading{Parameters}
1289 \docparam{name}{Handler name.}
1292 \membersection{wxImageHandler::SetExtension}\label{wximagehandlersetextension}
1294 \func{void}{SetExtension}{\param{const wxString\& }{extension}}
1296 Sets the handler extension.
1298 \wxheading{Parameters}
1300 \docparam{extension}{Handler extension.}
1303 \membersection{wxImageHandler::SetMimeType}\label{wximagehandlersetmimetype}
1305 \func{void}{SetMimeType}{\param{const wxString\& }{mimetype}}
1307 Sets the handler MIME type.
1309 \wxheading{Parameters}
1311 \docparam{mimename}{Handler MIME type.}
1314 \membersection{wxImageHandler::SetType}\label{wximagehandlersettype}
1316 \func{void}{SetType}{\param{long }{type}}
1318 Sets the handler type.
1320 \wxheading{Parameters}
1322 \docparam{name}{Handler type.}