]> git.saurik.com Git - wxWidgets.git/blame - docs/latex/wx/image.tex
clarified native line ending for Mac OS
[wxWidgets.git] / docs / latex / wx / image.tex
CommitLineData
1e6d9499
JS
1\section{\class{wxImage}}\label{wximage}
2
3This class encapsulates a platform-independent image. An image can be created
b06a6b20 4from data, or using \helpref{wxBitmap::ConvertToImage}{wxbitmapconverttoimage}. An image
1e6d9499
JS
5can be loaded from a file in a variety of formats, and is extensible to new formats
6via image format handlers. Functions are available to set and get image bits, so
7it can be used for basic image manipulation.
8
7468b994
RR
9A wxImage cannot (currently) be drawn directly to a \helpref{wxDC}{wxdc}. Instead,
10a platform-specific \helpref{wxBitmap}{wxbitmap} object must be created from it using
b06a6b20
VS
11the \helpref{wxBitmap::wxBitmap(wxImage,int depth)}{wxbitmapconstr} constructor.
12This bitmap can then
7468b994
RR
13be drawn in a device context, using \helpref{wxDC::DrawBitmap}{wxdcdrawbitmap}.
14
15One colour value of the image may be used as a mask colour which will lead to the automatic
16creation of a \helpref{wxMask}{wxmask} object associated to the bitmap object.
12a44087 17
8727a1fe
GRG
18\wxheading{Available image handlers}
19
20The following image handlers are available. {\bf wxBMPHandler} is always
21installed by default. To use other image formats, install the appropiate
fa482912 22handler with \helpref{wxImage::AddHandler}{wximageaddhandler} or
8727a1fe
GRG
23\helpref{wxInitAllImageHandlers}{wxinitallimagehandlers}.
24
25\twocolwidtha{5cm}%
26\begin{twocollist}
606a3178
GT
27\twocolitem{\indexit{wxBMPHandler}}{Only for loading, always installed.}
28\twocolitem{\indexit{wxPNGHandler}}{For loading and saving.}
29\twocolitem{\indexit{wxJPEGHandler}}{For loading and saving.}
30\twocolitem{\indexit{wxGIFHandler}}{Only for loading, due to legal issues.}
31\twocolitem{\indexit{wxPCXHandler}}{For loading and saving (see below).}
32\twocolitem{\indexit{wxPNMHandler}}{For loading and saving (see below).}
b86e511a
VS
33\twocolitem{\indexit{wxTIFFHandler}}{For loading and saving.}
34\twocolitem{\indexit{wxXPMHandler}}{For loading and saving.}
8727a1fe
GRG
35\end{twocollist}
36
37When saving in PCX format, {\bf wxPCXHandler} will count the number of
38different colours in the image; if there are 256 or less colours, it will
39save as 8 bit, else it will save as 24 bit.
40
41Loading PNMs only works for ASCII or raw RGB images. When saving in
42PNM format, {\bf wxPNMHandler} will always save as raw RGB.
43
1e6d9499
JS
44\wxheading{Derived from}
45
46\helpref{wxObject}{wxobject}
47
954b8ae6
JS
48\wxheading{Include files}
49
50<wx/image.h>
51
1e6d9499
JS
52\wxheading{See also}
53
f6081a04 54\helpref{wxBitmap}{wxbitmap},
b5a4a47d 55\helpref{wxInitAllImageHandlers}{wxinitallimagehandlers}
1e6d9499
JS
56
57\latexignore{\rtfignore{\wxheading{Members}}}
58
59\membersection{wxImage::wxImage}\label{wximageconstr}
60
61\func{}{wxImage}{\void}
62
63Default constructor.
64
65\func{}{wxImage}{\param{const wxImage\& }{image}}
66
67Copy constructor.
68
69\func{}{wxImage}{\param{const wxBitmap\&}{ bitmap}}
70
b06a6b20
VS
71(Deprecated form, use \helpref{wxBitmap::ConvertToImage}{wxbitmapconverttoimage}
72instead.) Constructs an image from a platform-dependent bitmap. This preserves
12a44087
RR
73mask information so that bitmaps and images can be converted back
74and forth without loss in that respect.
1e6d9499
JS
75
76\func{}{wxImage}{\param{int}{ width}, \param{int}{ height}}
77
78Creates an image with the given width and height.
79
e7240349 80\func{}{wxImage}{\param{int}{ width}, \param{int}{ height}, \param{unsigned char*}{ data}, \param{bool}{ static\_data=FALSE}}
f6bcfd97
BP
81
82Creates an image from given data with the given width and height. If
e7240349 83{\it static\_data} is TRUE, then wxImage will not delete the actual
f6bcfd97
BP
84image data in its destructor, otherwise it will free it by calling
85{\it free()}.
86
087c0d5e 87\func{}{wxImage}{\param{const wxString\& }{name}, \param{long}{ type = wxBITMAP\_TYPE\_ANY}}
1e6d9499 88
9e9ee68e
VS
89\func{}{wxImage}{\param{const wxString\& }{name}, \param{const wxString\&}{ mimetype}}
90
1e6d9499
JS
91Loads an image from a file.
92
087c0d5e 93\func{}{wxImage}{\param{wxInputStream\& }{stream}, \param{long}{ type = wxBITMAP\_TYPE\_ANY}}
45b5751f 94
9e9ee68e
VS
95\func{}{wxImage}{\param{wxInputStream\& }{stream}, \param{const wxString\&}{ mimetype}}
96
45b5751f
JS
97Loads an image from an input stream.
98
1e6d9499
JS
99\wxheading{Parameters}
100
101\docparam{width}{Specifies the width of the image.}
102
103\docparam{height}{Specifies the height of the image.}
104
31fd9b6b 105\docparam{name}{Name of the file from which to load the image.}
1e6d9499 106
31fd9b6b 107\docparam{stream}{Opened input stream from which to load the image. Currently, the stream must support seeking.}
45b5751f 108
1e6d9499
JS
109\docparam{type}{May be one of the following:
110
6be663cf 111\twocolwidtha{5cm}%
1e6d9499 112\begin{twocollist}
606a3178
GT
113\twocolitem{\indexit{wxBITMAP\_TYPE\_BMP}}{Load a Windows bitmap file.}
114\twocolitem{\indexit{wxBITMAP\_TYPE\_GIF}}{Load a GIF bitmap file.}
115\twocolitem{\indexit{wxBITMAP\_TYPE\_JPEG}}{Load a JPEG bitmap file.}
116\twocolitem{\indexit{wxBITMAP\_TYPE\_PNG}}{Load a PNG bitmap file.}
117\twocolitem{\indexit{wxBITMAP\_TYPE\_PCX}}{Load a PCX bitmap file.}
118\twocolitem{\indexit{wxBITMAP\_TYPE\_PNM}}{Load a PNM bitmap file.}
119\twocolitem{\indexit{wxBITMAP\_TYPE\_TIF}}{Load a TIFF bitmap file.}
b86e511a 120\twocolitem{\indexit{wxBITMAP\_TYPE\_XPM}}{Load a XPM bitmap file.}
606a3178 121\twocolitem{\indexit{wxBITMAP\_TYPE\_ANY}}{Will try to autodetect the format.}
31fd9b6b 122\end{twocollist}}
1e6d9499 123
9e9ee68e
VS
124\docparam{mimetype}{MIME type string (for example 'image/jpeg')}
125
31fd9b6b
GRG
126\wxheading{Remarks}
127
128Depending on how wxWindows has been configured, not all formats may be available.
129
fa482912
JS
130Note: any handler other than BMP must be previously
131initialized with \helpref{wxImage::AddHandler}{wximageaddhandler} or
31fd9b6b 132\helpref{wxInitAllImageHandlers}{wxinitallimagehandlers}.
0a9f2522 133
1e6d9499
JS
134\wxheading{See also}
135
136\helpref{wxImage::LoadFile}{wximageloadfile}
137
f899db6d
RD
138\pythonnote{Constructors supported by wxPython are:\par
139\indented{2cm}{\begin{twocollist}
c9110876
VS
140\twocolitem{{\bf wxImage(name, flag)}}{Loads an image from a file}
141\twocolitem{{\bf wxNullImage()}}{Create a null image (has no size or
f899db6d 142image data)}
c9110876 143\twocolitem{{\bf wxEmptyImage(width, height)}}{Creates an empty image
f899db6d 144of the given size}
c9110876 145\twocolitem{{\bf wxImageFromMime(name, mimetype}}{Creates an image from
f899db6d 146the given file of the given mimetype}
c9110876 147\twocolitem{{\bf wxImageFromBitmap(bitmap)}}{Creates an image from a
f899db6d
RD
148platform-dependent bitmap}
149\end{twocollist}}
150}
151
5873607e
VZ
152\perlnote{Constructors supported by wxPerl are:\par
153\begin{itemize}
154\item{Wx::Image->new( bitmap )}
155\item{Wx::Image->new( width, height )}
156\item{Wx::Image->new( name, type )}
157\item{Wx::Image->new( name, mimetype )}
158\end{itemize}
159}
160
1e6d9499
JS
161\membersection{wxImage::\destruct{wxImage}}
162
163\func{}{\destruct{wxImage}}{\void}
164
165Destructor.
166
167\membersection{wxImage::AddHandler}\label{wximageaddhandler}
168
169\func{static void}{AddHandler}{\param{wxImageHandler*}{ handler}}
170
171Adds a handler to the end of the static list of format handlers.
172
173\docparam{handler}{A new image format handler object. There is usually only one instance
174of a given handler class in an application session.}
175
176\wxheading{See also}
177
178\helpref{wxImageHandler}{wximagehandler}
179
e7240349 180\pythonnote{In wxPython this static method is named {\tt wxImage\_AddHandler}.}
1e6d9499
JS
181\membersection{wxImage::CleanUpHandlers}
182
183\func{static void}{CleanUpHandlers}{\void}
184
185Deletes all image handlers.
186
187This function is called by wxWindows on exit.
188
189\membersection{wxImage::ConvertToBitmap}\label{wximageconverttobitmap}
190
191\constfunc{wxBitmap}{ConvertToBitmap}{\void}
192
b06a6b20
VS
193Deprecated, use equivalent \helpref{wxBitmap constructor}{wxbitmapconstr}
194(which takes wxImage and depth as its arguments) instead.
7468b994 195
b06a6b20 196\membersection{wxImage::ConvertToMono}\label{wxbitmapconverttomono}
1e6d9499 197
b06a6b20
VS
198\constfunc{wxImage}{ConvertToMono}{\param{unsigned char}{ r}, \param{unsigned char}{ g}, \param{unsigned char}{ b}}
199
200Returns monochromatic version of the image. The returned image has white
201colour where the original has {\it (r,g,b)} colour and black colour
202everywhere else.
3ca6a5f0 203
f6bcfd97
BP
204\membersection{wxImage::Copy}\label{wximagecopy}
205
206\constfunc{wxImage}{Copy}{\void}
207
208Returns an identical copy of the image.
209
1e6d9499
JS
210\membersection{wxImage::Create}\label{wximagecreate}
211
212\func{bool}{Create}{\param{int}{ width}, \param{int}{ height}}
213
214Creates a fresh image.
215
216\wxheading{Parameters}
217
218\docparam{width}{The width of the image in pixels.}
219
220\docparam{height}{The height of the image in pixels.}
221
222\wxheading{Return value}
223
224TRUE if the call succeeded, FALSE otherwise.
225
226\membersection{wxImage::Destroy}\label{wximagedestroy}
227
228\func{bool}{Destroy}{\void}
229
230Destroys the image data.
231
232\membersection{wxImage::FindHandler}
233
234\func{static wxImageHandler*}{FindHandler}{\param{const wxString\& }{name}}
235
236Finds the handler with the given name.
237
238\func{static wxImageHandler*}{FindHandler}{\param{const wxString\& }{extension}, \param{long}{ imageType}}
239
240Finds the handler associated with the given extension and type.
241
242\func{static wxImageHandler*}{FindHandler}{\param{long }{imageType}}
243
244Finds the handler associated with the given image type.
245
9e9ee68e
VS
246\func{static wxImageHandler*}{FindHandlerMime}{\param{const wxString\& }{mimetype}}
247
248Finds the handler associated with the given MIME type.
249
1e6d9499
JS
250\docparam{name}{The handler name.}
251
252\docparam{extension}{The file extension, such as ``bmp".}
253
f6fcbb63 254\docparam{imageType}{The image type, such as wxBITMAP\_TYPE\_BMP.}
1e6d9499 255
9e9ee68e
VS
256\docparam{mimetype}{MIME type.}
257
1e6d9499
JS
258\wxheading{Return value}
259
260A pointer to the handler if found, NULL otherwise.
261
262\wxheading{See also}
263
264\helpref{wxImageHandler}{wximagehandler}
265
266\membersection{wxImage::GetBlue}\label{wximagegetblue}
267
268\constfunc{unsigned char}{GetBlue}{\param{int}{ x}, \param{int}{ y}}
269
270Returns the blue intensity at the given coordinate.
271
272\membersection{wxImage::GetData}\label{wximagegetdata}
273
274\constfunc{unsigned char*}{GetData}{\void}
275
12a44087
RR
276Returns the image data as an array. This is most often used when doing
277direct image manipulation. The return value points to an array of
278chararcters in RGBGBRGB... format.
1e6d9499
JS
279
280\membersection{wxImage::GetGreen}\label{wximagegetgreen}
281
282\constfunc{unsigned char}{GetGreen}{\param{int}{ x}, \param{int}{ y}}
283
284Returns the green intensity at the given coordinate.
285
286\membersection{wxImage::GetRed}\label{wximagegetred}
287
288\constfunc{unsigned char}{GetRed}{\param{int}{ x}, \param{int}{ y}}
289
290Returns the red intensity at the given coordinate.
291
292\membersection{wxImage::GetHandlers}
293
294\func{static wxList\&}{GetHandlers}{\void}
295
296Returns the static list of image format handlers.
297
298\wxheading{See also}
299
300\helpref{wxImageHandler}{wximagehandler}
301
302\membersection{wxImage::GetHeight}\label{wximagegetheight}
303
304\constfunc{int}{GetHeight}{\void}
305
306Gets the height of the image in pixels.
307
308\membersection{wxImage::GetMaskBlue}\label{wximagegetmaskblue}
309
310\constfunc{unsigned char}{GetMaskBlue}{\void}
311
312Gets the blue value of the mask colour.
313
314\membersection{wxImage::GetMaskGreen}\label{wximagegetmaskgreen}
315
316\constfunc{unsigned char}{GetMaskGreen}{\void}
317
318Gets the green value of the mask colour.
319
320\membersection{wxImage::GetMaskRed}\label{wximagegetmaskred}
321
322\constfunc{unsigned char}{GetMaskRed}{\void}
323
324Gets the red value of the mask colour.
325
3ca6a5f0
BP
326\membersection{wxImage::GetPalette}\label{wximagegetpalette}
327
328\constfunc{const wxPalette\&}{GetPalette}{\void}
329
330Returns the palette associated with the image. Currently the palette is only
b06a6b20 331used when converting to wxBitmap under Windows.
3ca6a5f0
BP
332
333Eventually wxImage handlers will set the palette if one exists in the image file.
334
fc9c7c09
RR
335\membersection{wxImage::GetSubImage}\label{wximagegetsubimage}
336
7468b994 337\constfunc{wxImage}{GetSubImage}{\param{const wxRect\&}{ rect}}
fc9c7c09
RR
338
339Returns a sub image of the current one as long as the rect belongs entirely to
340the image.
341
1e6d9499
JS
342\membersection{wxImage::GetWidth}\label{wximagegetwidth}
343
344\constfunc{int}{GetWidth}{\void}
345
346Gets the width of the image in pixels.
347
348\wxheading{See also}
349
350\helpref{wxImage::GetHeight}{wximagegetheight}
351
352\membersection{wxImage::HasMask}\label{wximagehasmask}
353
354\constfunc{bool}{HasMask}{\void}
355
356Returns TRUE if there is a mask active, FALSE otherwise.
357
5e5437e0
JS
358\membersection{wxImage::GetOption}\label{wximagegetoption}
359
360\constfunc{wxString}{GetOption}{\param{const wxString\&}{ name}}
361
362Gets a user-defined option. The function is case-insensitive to {\it name}.
363
364For example, when saving as a JPEG file, the option {\bf quality} is
365used, which is a number between 0 and 100 (0 is terrible, 100 is very good).
366
367\wxheading{See also}
368
369\helpref{wxImage::SetOption}{wximagesetoption},\rtfsp
370\helpref{wxImage::GetOptionInt}{wximagegetoptionint},\rtfsp
371\helpref{wxImage::HasOption}{wximagehasoption}
372
373\membersection{wxImage::GetOptionInt}\label{wximagegetoptionint}
374
375\constfunc{int}{GetOptionInt}{\param{const wxString\&}{ name}}
376
377Gets a user-defined option as an integer. The function is case-insensitive to {\it name}.
378
379\wxheading{See also}
380
381\helpref{wxImage::SetOption}{wximagesetoption},\rtfsp
382\helpref{wxImage::GetOption}{wximagegetoption},\rtfsp
383\helpref{wxImage::HasOption}{wximagehasoption}
384
385\membersection{wxImage::HasOption}\label{wximagehasoption}
386
387\constfunc{bool}{HasOption}{\param{const wxString\&}{ name}}
388
389Returns TRUE if the given option is present. The function is case-insensitive to {\it name}.
390
391\wxheading{See also}
392
393\helpref{wxImage::SetOption}{wximagesetoption},\rtfsp
394\helpref{wxImage::GetOption}{wximagegetoption},\rtfsp
395\helpref{wxImage::GetOptionInt}{wximagegetoptionint}
396
1e6d9499
JS
397\membersection{wxImage::InitStandardHandlers}
398
399\func{static void}{InitStandardHandlers}{\void}
400
a14e57f9 401Internal use only. Adds standard image format handlers. It only install BMP
31fd9b6b 402for the time being, which is used by wxBitmap.
1e6d9499 403
a14e57f9
SB
404This function is called by wxWindows on startup, and shouldn't be called by
405the user.
1e6d9499
JS
406
407\wxheading{See also}
408
fa482912 409\helpref{wxImageHandler}{wximagehandler},
b5a4a47d 410\helpref{wxInitAllImageHandlers}{wxinitallimagehandlers}
1e6d9499
JS
411
412\membersection{wxImage::InsertHandler}
413
414\func{static void}{InsertHandler}{\param{wxImageHandler*}{ handler}}
415
416Adds a handler at the start of the static list of format handlers.
417
418\docparam{handler}{A new image format handler object. There is usually only one instance
419of a given handler class in an application session.}
420
421\wxheading{See also}
422
423\helpref{wxImageHandler}{wximagehandler}
424
425\membersection{wxImage::LoadFile}\label{wximageloadfile}
426
a14e57f9 427\func{bool}{LoadFile}{\param{const wxString\&}{ name}, \param{long}{ type = wxBITMAP\_TYPE\_ANY}}
1e6d9499 428
9e9ee68e
VS
429\func{bool}{LoadFile}{\param{const wxString\&}{ name}, \param{const wxString\&}{ mimetype}}
430
a14e57f9 431Loads an image from a file. If no handler type is provided, the library will
31fd9b6b 432try to autodetect the format.
1e6d9499 433
45b5751f
JS
434\func{bool}{LoadFile}{\param{wxInputStream\&}{ stream}, \param{long}{ type}}
435
9e9ee68e
VS
436\func{bool}{LoadFile}{\param{wxInputStream\&}{ stream}, \param{const wxString\&}{ mimetype}}
437
45b5751f
JS
438Loads an image from an input stream.
439
1e6d9499
JS
440\wxheading{Parameters}
441
31fd9b6b 442\docparam{name}{Name of the file from which to load the image.}
1e6d9499 443
31fd9b6b 444\docparam{stream}{Opened input stream from which to load the image. Currently, the stream must support seeking.}
45b5751f 445
1e6d9499
JS
446\docparam{type}{One of the following values:
447
6be663cf 448\twocolwidtha{5cm}%
1e6d9499 449\begin{twocollist}
f6fcbb63 450\twocolitem{{\bf wxBITMAP\_TYPE\_BMP}}{Load a Windows image file.}
a14e57f9 451\twocolitem{{\bf wxBITMAP\_TYPE\_GIF}}{Load a GIF image file.}
48b4e302 452\twocolitem{{\bf wxBITMAP\_TYPE\_JPEG}}{Load a JPEG image file.}
a14e57f9
SB
453\twocolitem{{\bf wxBITMAP\_TYPE\_PCX}}{Load a PCX image file.}
454\twocolitem{{\bf wxBITMAP\_TYPE\_PNG}}{Load a PNG image file.}
455\twocolitem{{\bf wxBITMAP\_TYPE\_PNM}}{Load a PNM image file.}
31fd9b6b 456\twocolitem{{\bf wxBITMAP\_TYPE\_TIF}}{Load a TIFF image file.}
b86e511a 457\twocolitem{{\bf wxBITMAP\_TYPE\_XPM}}{Load a XPM image file.}
31fd9b6b
GRG
458\twocolitem{{\bf wxBITMAP\_TYPE\_ANY}}{Will try to autodetect the format.}
459\end{twocollist}}
1e6d9499 460
9e9ee68e
VS
461\docparam{mimetype}{MIME type string (for example 'image/jpeg')}
462
31fd9b6b
GRG
463\wxheading{Remarks}
464
465Depending on how wxWindows has been configured, not all formats may be available.
466
1e6d9499
JS
467\wxheading{Return value}
468
469TRUE if the operation succeeded, FALSE otherwise.
470
471\wxheading{See also}
472
473\helpref{wxImage::SaveFile}{wximagesavefile}
474
f899db6d
RD
475\pythonnote{In place of a single overloaded method name, wxPython
476implements the following methods:\par
477\indented{2cm}{\begin{twocollist}
c9110876 478\twocolitem{{\bf LoadFile(filename, type)}}{Loads an image of the given
f899db6d 479type from a file}
c9110876 480\twocolitem{{\bf LoadMimeFile(filename, mimetype)}}{Loads an image of the given
f899db6d
RD
481mimetype from a file}
482\end{twocollist}}
483}
484
5873607e
VZ
485\perlnote{Methods supported by wxPerl are:\par
486\begin{itemize}
606a3178
GT
487\item{bitmap->LoadFile( name, type )}
488\item{bitmap->LoadFile( name, mimetype )}
5873607e
VZ
489\end{itemize}
490}
491
f899db6d 492
1e6d9499
JS
493\membersection{wxImage::Ok}\label{wximageok}
494
495\constfunc{bool}{Ok}{\void}
496
497Returns TRUE if image data is present.
498
499\membersection{wxImage::RemoveHandler}
500
501\func{static bool}{RemoveHandler}{\param{const wxString\& }{name}}
502
503Finds the handler with the given name, and removes it. The handler
504is not deleted.
505
506\docparam{name}{The handler name.}
507
508\wxheading{Return value}
509
510TRUE if the handler was found and removed, FALSE otherwise.
511
512\wxheading{See also}
513
514\helpref{wxImageHandler}{wximagehandler}
515
516\membersection{wxImage::SaveFile}\label{wximagesavefile}
517
518\func{bool}{SaveFile}{\param{const wxString\& }{name}, \param{int}{ type}}
519
9e9ee68e
VS
520\func{bool}{SaveFile}{\param{const wxString\& }{name}, \param{const wxString\&}{ mimetype}}
521
1e6d9499
JS
522Saves a image in the named file.
523
45b5751f
JS
524\func{bool}{SaveFile}{\param{wxOutputStream\& }{stream}, \param{int}{ type}}
525
9e9ee68e
VS
526\func{bool}{SaveFile}{\param{wxOutputStream\& }{stream}, \param{const wxString\&}{ mimetype}}
527
45b5751f
JS
528Saves a image in the given stream.
529
1e6d9499
JS
530\wxheading{Parameters}
531
31fd9b6b 532\docparam{name}{Name of the file to save the image to.}
1e6d9499 533
31fd9b6b 534\docparam{stream}{Opened output stream to save the image to.}
45b5751f 535
7468b994 536\docparam{type}{Currently three types can be used:
1e6d9499 537
6be663cf 538\twocolwidtha{5cm}%
1e6d9499 539\begin{twocollist}
48b4e302 540\twocolitem{{\bf wxBITMAP\_TYPE\_JPEG}}{Save a JPEG image file.}
31fd9b6b
GRG
541\twocolitem{{\bf wxBITMAP\_TYPE\_PNG}}{Save a PNG image file.}
542\twocolitem{{\bf wxBITMAP\_TYPE\_PCX}}{Save a PCX image file (tries to save as 8-bit if possible, falls back to 24-bit otherwise).}
543\twocolitem{{\bf wxBITMAP\_TYPE\_PNM}}{Save a PNM image file (as raw RGB always).}
b86e511a
VS
544\twocolitem{{\bf wxBITMAP\_TYPE\_TIFF}}{Save a TIFF image file.}
545\twocolitem{{\bf wxBITMAP\_TYPE\_XPM}}{Save a XPM image file.}
31fd9b6b 546\end{twocollist}}
1e6d9499 547
9e9ee68e
VS
548\docparam{mimetype}{MIME type.}
549
1e6d9499
JS
550\wxheading{Return value}
551
552TRUE if the operation succeeded, FALSE otherwise.
553
554\wxheading{Remarks}
555
556Depending on how wxWindows has been configured, not all formats may be available.
557
558\wxheading{See also}
559
560\helpref{wxImage::LoadFile}{wximageloadfile}
561
f899db6d
RD
562\pythonnote{In place of a single overloaded method name, wxPython
563implements the following methods:\par
564\indented{2cm}{\begin{twocollist}
c9110876 565\twocolitem{{\bf SaveFile(filename, type)}}{Saves the image using the given
f899db6d 566type to the named file}
c9110876 567\twocolitem{{\bf SaveMimeFile(filename, mimetype)}}{Saves the image using the given
f899db6d
RD
568mimetype to the named file}
569\end{twocollist}}
570}
571
5873607e
VZ
572\perlnote{Methods supported by wxPerl are:\par
573\begin{itemize}
606a3178
GT
574\item{bitmap->SaveFile( name, type )}
575\item{bitmap->SaveFile( name, mimetype )}
5873607e
VZ
576\end{itemize}
577}
578
f6bcfd97
BP
579\membersection{wxImage::Mirror}\label{wximagemirror}
580
581\constfunc{wxImage}{Mirror}{\param{bool}{ horizontally = TRUE}}
582
583Returns a mirrored copy of the image. The parameter {\it horizontally}
584indicates the orientation.
585
7468b994
RR
586\membersection{wxImage::Replace}\label{wximagereplace}
587
588\func{void}{Replace}{\param{unsigned char}{ r1}, \param{unsigned char}{ g1}, \param{unsigned char}{ b1},
589\param{unsigned char}{ r2}, \param{unsigned char}{ g2}, \param{unsigned char}{ b2}}
590
591Replaces the colour specified by {\it r1,g1,b1} by the colour {\it r2,g2,b2}.
592
ce9a75d2
VZ
593\membersection{wxImage::Rescale}\label{wximagerescale}
594
6e807169 595\func{wxImage \&}{Rescale}{\param{int}{ width}, \param{int}{ height}}
ce9a75d2 596
9c884972
RR
597Changes the size of the image in-place: after a call to this function, the
598image will have the given width and height.
ce9a75d2 599
6e807169
VZ
600Returns the (modified) image itself.
601
ce9a75d2
VZ
602\wxheading{See also}
603
604\helpref{Scale}{wximagescale}
605
ed8297b9 606\membersection{wxImage::Rotate}\label{wximagerotate}
7a632f10
JS
607
608\func{wxImage}{Rotate}{\param{double}{ angle}, \param{const wxPoint\& }{rotationCentre},
609 \param{bool}{ interpolating = TRUE}, \param{wxPoint*}{ offsetAfterRotation = NULL}}
610
611Rotates the image about the given point, by {\it angle} radians. Passing TRUE
b4e87ec3
GRG
612to {\it interpolating} results in better image quality, but is slower. If the
613image has a mask, then the mask colour is used for the uncovered pixels in the
614rotated image background. Else, black (rgb 0, 0, 0) will be used.
7a632f10
JS
615
616Returns the rotated image, leaving this image intact.
617
f6bcfd97
BP
618\membersection{wxImage::Rotate90}\label{wximagerotate90}
619
620\constfunc{wxImage}{Rotate90}{\param{bool}{ clockwise = TRUE}}
621
622Returns a copy of the image rotated 90 degrees in the direction
623indicated by {\it clockwise}.
624
1e6d9499
JS
625\membersection{wxImage::Scale}\label{wximagescale}
626
ce9a75d2 627\constfunc{wxImage}{Scale}{\param{int}{ width}, \param{int}{ height}}
1e6d9499 628
12a44087
RR
629Returns a scaled version of the image. This is also useful for
630scaling bitmaps in general as the only other way to scale bitmaps
ce9a75d2
VZ
631is to blit a wxMemoryDC into another wxMemoryDC.
632
7468b994 633It may be mentioned that the GTK port uses this function internally
f6bcfd97 634to scale bitmaps when using mapping modes in wxDC.
ce9a75d2
VZ
635
636Example:
637
638\begin{verbatim}
639 // get the bitmap from somewhere
640 wxBitmap bmp = ...;
641
642 // rescale it to have size of 32*32
643 if ( bmp.GetWidth() != 32 || bmp.GetHeight() != 32 )
644 {
645 wxImage image(bmp);
b06a6b20 646 bmp = wxBitmap(image.Scale(32, 32));
ce9a75d2
VZ
647
648 // another possibility:
649 image.Rescale(32, 32);
650 bmp = image;
651 }
652
653\end{verbatim}
654
655\wxheading{See also}
656
657\helpref{Rescale}{wximagerescale}
1e6d9499
JS
658
659\membersection{wxImage::SetData}\label{wximagesetdata}
660
661\func{void}{SetData}{\param{unsigned char*}{data}}
662
f899db6d 663Sets the image data without performing checks. The data given must have
12a44087
RR
664the size (width*height*3) or results will be unexpected. Don't use this
665method if you aren't sure you know what you are doing.
1e6d9499
JS
666
667\membersection{wxImage::SetMask}\label{wximagesetmask}
668
669\func{void}{SetMask}{\param{bool}{ hasMask = TRUE}}
670
671Specifies whether there is a mask or not. The area of the mask is determined by the current mask colour.
672
673\membersection{wxImage::SetMaskColour}\label{wximagesetmaskcolour}
674
675\func{void}{SetMaskColour}{\param{unsigned char }{red}, \param{unsigned char }{blue}, \param{unsigned char }{green}}
676
b1170810 677Sets the mask colour for this image (and tells the image to use the mask).
1e6d9499 678
5e5437e0
JS
679\membersection{wxImage::SetOption}\label{wximagesetoption}
680
681\func{void}{SetOption}{\param{const wxString\&}{ name}, \param{const wxString\&}{ value}}
682
683\func{void}{SetOption}{\param{const wxString\&}{ name}, \param{int}{ value}}
684
685Sets a user-defined option. The function is case-insensitive to {\it name}.
686
687For example, when saving as a JPEG file, the option {\bf quality} is
688used, which is a number between 0 and 100 (0 is terrible, 100 is very good).
689
690\wxheading{See also}
691
692\helpref{wxImage::GetOption}{wximagegetoption},\rtfsp
693\helpref{wxImage::GetOptionInt}{wximagegetoptionint},\rtfsp
694\helpref{wxImage::HasOption}{wximagehasoption}
695
3ca6a5f0
BP
696\membersection{wxImage::SetPalette}\label{wximagesetpalette}
697
698\func{void}{SetPalette}{\param{const wxPalette\&}{ palette}}
699
b06a6b20
VS
700Associates a palette with the image. The palette may be used when converting
701wxImage to wxBitmap (MSW only at present) or in file save operations (none as yet).
3ca6a5f0 702
1e6d9499
JS
703\membersection{wxImage::SetRGB}\label{wximagesetrgb}
704
f6bcfd97 705\func{void}{SetRGB}{\param{int }{x}, \param{int }{y}, \param{unsigned char }{red}, \param{unsigned char }{green}, \param{unsigned char }{blue}}
1e6d9499 706
12a44087
RR
707Sets the pixel at the given coordinate. This routine performs bounds-checks
708for the coordinate so it can be considered a safe way to manipulate the
709data, but in some cases this might be too slow so that the data will have to
7468b994
RR
710be set directly. In that case you will have to get access to the image data
711using the \helpref{GetData}{wximagegetdata} method.
1e6d9499
JS
712
713\membersection{wxImage::operator $=$}
714
715\func{wxImage\& }{operator $=$}{\param{const wxImage\& }{image}}
716
717Assignment operator. This operator does not copy any data, but instead
718passes a pointer to the data in {\it image} and increments a reference
719counter. It is a fast operation.
720
721\wxheading{Parameters}
722
723\docparam{image}{Image to assign.}
724
725\wxheading{Return value}
726
727Returns 'this' object.
728
729\membersection{wxImage::operator $==$}
730
731\func{bool}{operator $==$}{\param{const wxImage\& }{image}}
732
733Equality operator. This operator tests whether the internal data pointers are
734equal (a fast test).
735
736\wxheading{Parameters}
737
738\docparam{image}{Image to compare with 'this'}
739
740\wxheading{Return value}
741
742Returns TRUE if the images were effectively equal, FALSE otherwise.
743
744\membersection{wxImage::operator $!=$}
745
746\func{bool}{operator $!=$}{\param{const wxImage\& }{image}}
747
748Inequality operator. This operator tests whether the internal data pointers are
749unequal (a fast test).
750
751\wxheading{Parameters}
752
753\docparam{image}{Image to compare with 'this'}
754
755\wxheading{Return value}
756
757Returns TRUE if the images were unequal, FALSE otherwise.
758
759\section{\class{wxImageHandler}}\label{wximagehandler}
760
1e6d9499
JS
761This is the base class for implementing image file loading/saving, and image creation from data.
762It is used within wxImage and is not normally seen by the application.
763
764If you wish to extend the capabilities of wxImage, derive a class from wxImageHandler
765and add the handler using \helpref{wxImage::AddHandler}{wximageaddhandler} in your
766application initialisation.
767
48b4e302
VS
768\wxheading{Note (Legal Issue)}
769
954b8ae6 770This software is based in part on the work of the Independent JPEG Group.
48b4e302
VS
771
772(Applies when wxWindows is linked with JPEG support. wxJPEGHandler uses libjpeg
773created by IJG.)
774
1e6d9499
JS
775\wxheading{Derived from}
776
777\helpref{wxObject}{wxobject}
778
954b8ae6
JS
779\wxheading{Include files}
780
781<wx/image.h>
782
1e6d9499
JS
783\wxheading{See also}
784
fa482912 785\helpref{wxImage}{wximage},
b5a4a47d 786\helpref{wxInitAllImageHandlers}{wxinitallimagehandlers}
1e6d9499
JS
787
788\latexignore{\rtfignore{\wxheading{Members}}}
789
790\membersection{wxImageHandler::wxImageHandler}\label{wximagehandlerconstr}
791
792\func{}{wxImageHandler}{\void}
793
794Default constructor. In your own default constructor, initialise the members
795m\_name, m\_extension and m\_type.
796
797\membersection{wxImageHandler::\destruct{wxImageHandler}}
798
799\func{}{\destruct{wxImageHandler}}{\void}
800
801Destroys the wxImageHandler object.
802
803\membersection{wxImageHandler::GetName}
804
805\constfunc{wxString}{GetName}{\void}
806
807Gets the name of this handler.
808
809\membersection{wxImageHandler::GetExtension}
810
811\constfunc{wxString}{GetExtension}{\void}
812
813Gets the file extension associated with this handler.
814
7941ba11
RR
815\membersection{wxImageHandler::GetImageCount}\label{wximagehandlergetimagecount}
816
817\func{int}{GetImageCount}{\param{wxInputStream\&}{ stream}}
818
819If the image file contains more than one image and the image handler is capable
820of retrieving these individually, this function will return the number of
821available images.
822
31fd9b6b 823\docparam{stream}{Opened input stream for reading image data. Currently, the stream must support seeking.}
7941ba11
RR
824
825\wxheading{Return value}
826
827Number of available images. For most image handles, this defaults to 1.
828
1e6d9499
JS
829\membersection{wxImageHandler::GetType}
830
831\constfunc{long}{GetType}{\void}
832
833Gets the image type associated with this handler.
834
9e9ee68e
VS
835\membersection{wxImageHandler::GetMimeType}
836
837\constfunc{wxString}{GetMimeType}{\void}
838
839Gets the MIME type associated with this handler.
840
1e6d9499
JS
841\membersection{wxImageHandler::LoadFile}\label{wximagehandlerloadfile}
842
7941ba11 843\func{bool}{LoadFile}{\param{wxImage* }{image}, \param{wxInputStream\&}{ stream}, \param{bool}{ verbose=TRUE}, \param{int}{ index=0}}
1e6d9499 844
7941ba11
RR
845Loads a image from a stream, putting the resulting data into {\it image}. If the image file contains
846more than one image and the image handler is capable of retrieving these individually, {\it index}
847indicates which image to read from the stream.
1e6d9499
JS
848
849\wxheading{Parameters}
850
851\docparam{image}{The image object which is to be affected by this operation.}
852
31fd9b6b 853\docparam{stream}{Opened input stream for reading image data.}
7941ba11
RR
854
855\docparam{verbose}{If set to TRUE, errors reported by the image handler will produce wxLogMessages.}
856
857\docparam{index}{The index of the image in the file (starting from zero).}
1e6d9499
JS
858
859\wxheading{Return value}
860
861TRUE if the operation succeeded, FALSE otherwise.
862
863\wxheading{See also}
864
fa482912
JS
865\helpref{wxImage::LoadFile}{wximageloadfile},
866\helpref{wxImage::SaveFile}{wximagesavefile},
1e6d9499
JS
867\helpref{wxImageHandler::SaveFile}{wximagehandlersavefile}
868
869\membersection{wxImageHandler::SaveFile}\label{wximagehandlersavefile}
870
45b5751f 871\func{bool}{SaveFile}{\param{wxImage* }{image}, \param{wxOutputStream\& }{stream}}
1e6d9499 872
45b5751f 873Saves a image in the output stream.
1e6d9499
JS
874
875\wxheading{Parameters}
876
877\docparam{image}{The image object which is to be affected by this operation.}
878
31fd9b6b 879\docparam{stream}{Opened output stream for writing the data.}
1e6d9499
JS
880
881\wxheading{Return value}
882
883TRUE if the operation succeeded, FALSE otherwise.
884
885\wxheading{See also}
886
fa482912
JS
887\helpref{wxImage::LoadFile}{wximageloadfile},
888\helpref{wxImage::SaveFile}{wximagesavefile},
1e6d9499
JS
889\helpref{wxImageHandler::LoadFile}{wximagehandlerloadfile}
890
891\membersection{wxImageHandler::SetName}
892
893\func{void}{SetName}{\param{const wxString\& }{name}}
894
895Sets the handler name.
896
897\wxheading{Parameters}
898
899\docparam{name}{Handler name.}
900
901\membersection{wxImageHandler::SetExtension}
902
903\func{void}{SetExtension}{\param{const wxString\& }{extension}}
904
905Sets the handler extension.
906
907\wxheading{Parameters}
908
909\docparam{extension}{Handler extension.}
910
f6bcfd97 911\membersection{wxImageHandler::SetMimeType}\label{wximagehandlersetmimetype}
1e6d9499 912
f6bcfd97 913\func{void}{SetMimeType}{\param{const wxString\& }{mimetype}}
1e6d9499 914
f6bcfd97 915Sets the handler MIME type.
1e6d9499
JS
916
917\wxheading{Parameters}
918
f6bcfd97 919\docparam{mimename}{Handler MIME type.}
9e9ee68e 920
f6bcfd97 921\membersection{wxImageHandler::SetType}
9e9ee68e 922
f6bcfd97 923\func{void}{SetType}{\param{long }{type}}
9e9ee68e 924
f6bcfd97 925Sets the handler type.
9e9ee68e
VS
926
927\wxheading{Parameters}
928
f6bcfd97 929\docparam{name}{Handler type.}
9e9ee68e 930