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