]> git.saurik.com Git - wxWidgets.git/blob - docs/latex/wx/image.tex
Build fix after DrawPushButton introduction.
[wxWidgets.git] / docs / latex / wx / image.tex
1 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
2 %% Name: image.tex
3 %% Purpose: wxImage documentation
4 %% Author: wxWidgets Team
5 %% Modified by:
6 %% Created:
7 %% RCS-ID: $Id$
8 %% Copyright: (c) wxWidgets Team
9 %% License: wxWindows license
10 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
11
12 \section{\class{wxImage}}\label{wximage}
13
14 This class encapsulates a platform-independent image. An image can be created
15 from data, or using \helpref{wxBitmap::ConvertToImage}{wxbitmapconverttoimage}. An image
16 can be loaded from a file in a variety of formats, and is extensible to new formats
17 via image format handlers. Functions are available to set and get image bits, so
18 it can be used for basic image manipulation.
19
20 A wxImage cannot (currently) be drawn directly to a \helpref{wxDC}{wxdc}. Instead,
21 a platform-specific \helpref{wxBitmap}{wxbitmap} object must be created from it using
22 the \helpref{wxBitmap::wxBitmap(wxImage,int depth)}{wxbitmapctor} constructor.
23 This bitmap can then
24 be drawn in a device context, using \helpref{wxDC::DrawBitmap}{wxdcdrawbitmap}.
25
26 One colour value of the image may be used as a mask colour which will lead to the automatic
27 creation of a \helpref{wxMask}{wxmask} object associated to the bitmap object.
28
29 \wxheading{Alpha channel support}
30
31 Starting from wxWidgets 2.5.0 wxImage supports alpha channel data, that is in
32 addition to a byte for the red, green and blue colour components for each pixel
33 it also stores a byte representing the pixel opacity. An alpha value of $0$
34 corresponds to a transparent pixel (null opacity) while a value of $255$
35 means that the pixel is 100\% opaque.
36
37 Unlike RGB data, not all images have an alpha channel and before using
38 \helpref{GetAlpha}{wximagegetalpha} you should check if this image contains
39 an alpha channel with \helpref{HasAlpha}{wximagehasalpha}. Note that currently only
40 images loaded from PNG files with transparency information will have an alpha
41 channel but alpha support will be added to the other formats as well (as well
42 as support for saving images with alpha channel which also isn't implemented).
43
44 \wxheading{Available image handlers}
45
46 The following image handlers are available. {\bf wxBMPHandler} is always
47 installed by default. To use other image formats, install the appropriate
48 handler with \helpref{wxImage::AddHandler}{wximageaddhandler} or
49 \helpref{wxInitAllImageHandlers}{wxinitallimagehandlers}.
50
51 \twocolwidtha{5cm}%
52 \begin{twocollist}
53 \twocolitem{\indexit{wxBMPHandler}}{For loading and saving, always installed.}
54 \twocolitem{\indexit{wxPNGHandler}}{For loading (including alpha support) and saving.}
55 \twocolitem{\indexit{wxJPEGHandler}}{For loading and saving.}
56 \twocolitem{\indexit{wxGIFHandler}}{Only for loading, due to legal issues.}
57 \twocolitem{\indexit{wxPCXHandler}}{For loading and saving (see below).}
58 \twocolitem{\indexit{wxPNMHandler}}{For loading and saving (see below).}
59 \twocolitem{\indexit{wxTIFFHandler}}{For loading and saving.}
60 \twocolitem{\indexit{wxIFFHandler}}{For loading only.}
61 \twocolitem{\indexit{wxXPMHandler}}{For loading and saving.}
62 \twocolitem{\indexit{wxICOHandler}}{For loading and saving.}
63 \twocolitem{\indexit{wxCURHandler}}{For loading and saving.}
64 \twocolitem{\indexit{wxANIHandler}}{For loading only.}
65 \end{twocollist}
66
67 When saving in PCX format, {\bf wxPCXHandler} will count the number of
68 different colours in the image; if there are 256 or less colours, it will
69 save as 8 bit, else it will save as 24 bit.
70
71 Loading PNMs only works for ASCII or raw RGB images. When saving in
72 PNM format, {\bf wxPNMHandler} will always save as raw RGB.
73
74 \wxheading{Derived from}
75
76 \helpref{wxObject}{wxobject}
77
78 \wxheading{Include files}
79
80 <wx/image.h>
81
82 \wxheading{See also}
83
84 \helpref{wxBitmap}{wxbitmap},
85 \helpref{wxInitAllImageHandlers}{wxinitallimagehandlers}
86
87 \latexignore{\rtfignore{\wxheading{Members}}}
88
89
90 \membersection{wxImage::wxImage}\label{wximagector}
91
92 \func{}{wxImage}{\void}
93
94 Default constructor.
95
96 \func{}{wxImage}{\param{const wxImage\& }{image}}
97
98 Copy constructor.
99
100 \func{}{wxImage}{\param{const wxBitmap\&}{ bitmap}}
101
102 (Deprecated form, use \helpref{wxBitmap::ConvertToImage}{wxbitmapconverttoimage}
103 instead.) Constructs an image from a platform-dependent bitmap. This preserves
104 mask information so that bitmaps and images can be converted back
105 and forth without loss in that respect.
106
107 \func{}{wxImage}{\param{int}{ width}, \param{int}{ height}, \param{bool}{ clear=true}}
108
109 Creates an image with the given width and height. If {\it clear} is true, the new image will be initialized to black.
110 Otherwise, the image data will be uninitialized.
111
112 \func{}{wxImage}{\param{int}{ width}, \param{int}{ height}, \param{unsigned char*}{ data}, \param{bool}{ static\_data = \false}}
113
114 Creates an image from given data with the given width and height. If
115 {\it static\_data} is true, then wxImage will not delete the actual
116 image data in its destructor, otherwise it will free it by calling
117 {\it free()}.
118
119 \func{}{wxImage}{\param{const wxString\& }{name}, \param{long}{ type = wxBITMAP\_TYPE\_ANY}, \param{int}{ index = -1}}
120
121 \func{}{wxImage}{\param{const wxString\& }{name}, \param{const wxString\&}{ mimetype}, \param{int}{ index = -1}}
122
123 Loads an image from a file.
124
125 \func{}{wxImage}{\param{wxInputStream\& }{stream}, \param{long}{ type = wxBITMAP\_TYPE\_ANY}, \param{int}{ index = -1}}
126
127 \func{}{wxImage}{\param{wxInputStream\& }{stream}, \param{const wxString\&}{ mimetype}, \param{int}{ index = -1}}
128
129 Loads an image from an input stream.
130
131 \func{}{wxImage}{\param{const char** }{xpmData}}
132
133 Creates an image from XPM data.
134
135 \wxheading{Parameters}
136
137 \docparam{width}{Specifies the width of the image.}
138
139 \docparam{height}{Specifies the height of the image.}
140
141 \docparam{name}{Name of the file from which to load the image.}
142
143 \docparam{stream}{Opened input stream from which to load the image. Currently, the stream must support seeking.}
144
145 \docparam{type}{May be one of the following:
146
147 \twocolwidtha{5cm}%
148 \begin{twocollist}
149 \twocolitem{\indexit{wxBITMAP\_TYPE\_BMP}}{Load a Windows bitmap file.}
150 \twocolitem{\indexit{wxBITMAP\_TYPE\_GIF}}{Load a GIF bitmap file.}
151 \twocolitem{\indexit{wxBITMAP\_TYPE\_JPEG}}{Load a JPEG bitmap file.}
152 \twocolitem{\indexit{wxBITMAP\_TYPE\_PNG}}{Load a PNG bitmap file.}
153 \twocolitem{\indexit{wxBITMAP\_TYPE\_PCX}}{Load a PCX bitmap file.}
154 \twocolitem{\indexit{wxBITMAP\_TYPE\_PNM}}{Load a PNM bitmap file.}
155 \twocolitem{\indexit{wxBITMAP\_TYPE\_TIF}}{Load a TIFF bitmap file.}
156 \twocolitem{\indexit{wxBITMAP\_TYPE\_XPM}}{Load a XPM bitmap file.}
157 \twocolitem{\indexit{wxBITMAP\_TYPE\_ICO}}{Load a Windows icon file (ICO).}
158 \twocolitem{\indexit{wxBITMAP\_TYPE\_CUR}}{Load a Windows cursor file (CUR).}
159 \twocolitem{\indexit{wxBITMAP\_TYPE\_ANI}}{Load a Windows animated cursor file (ANI).}
160 \twocolitem{\indexit{wxBITMAP\_TYPE\_ANY}}{Will try to autodetect the format.}
161 \end{twocollist}}
162
163 \docparam{mimetype}{MIME type string (for example 'image/jpeg')}
164
165 \docparam{index}{Index of the image to load in the case that the image file contains multiple images.
166 This is only used by GIF, ICO and TIFF handlers. The default value (-1) means
167 "choose the default image" and is interpreted as the first image (index=0) by
168 the GIF and TIFF handler and as the largest and most colourful one by the ICO handler.}
169
170 \docparam{xpmData}{A pointer to XPM image data.}
171
172 \wxheading{Remarks}
173
174 Depending on how wxWidgets has been configured, not all formats may be available.
175
176 Note: any handler other than BMP must be previously
177 initialized with \helpref{wxImage::AddHandler}{wximageaddhandler} or
178 \helpref{wxInitAllImageHandlers}{wxinitallimagehandlers}.
179
180 Note: you can use \helpref{GetOptionInt}{wximagegetoptionint} to get the
181 hotspot for loaded cursor file:
182 \begin{verbatim}
183 int hotspot_x = image.GetOptionInt(wxIMAGE_OPTION_CUR_HOTSPOT_X);
184 int hotspot_y = image.GetOptionInt(wxIMAGE_OPTION_CUR_HOTSPOT_Y);
185
186 \end{verbatim}
187
188 \wxheading{See also}
189
190 \helpref{wxImage::LoadFile}{wximageloadfile}
191
192 \pythonnote{Constructors supported by wxPython are:\par
193 \indented{2cm}{\begin{twocollist}
194 \twocolitem{{\bf wxImage(name, flag)}}{Loads an image from a file}
195 \twocolitem{{\bf wxNullImage()}}{Create a null image (has no size or
196 image data)}
197 \twocolitem{{\bf wxEmptyImage(width, height)}}{Creates an empty image
198 of the given size}
199 \twocolitem{{\bf wxImageFromMime(name, mimetype}}{Creates an image from
200 the given file of the given mimetype}
201 \twocolitem{{\bf wxImageFromBitmap(bitmap)}}{Creates an image from a
202 platform-dependent bitmap}
203 \end{twocollist}}
204 }
205
206 \perlnote{Constructors supported by wxPerl are:\par
207 \begin{itemize}
208 \item{Wx::Image->new( bitmap )}
209 \item{Wx::Image->new( icon )}
210 \item{Wx::Image->new( width, height )}
211 \item{Wx::Image->new( width, height, data )}
212 \item{Wx::Image->new( file, type, index )}
213 \item{Wx::Image->new( file, mimetype, index )}
214 \item{Wx::Image->new( stream, type, index )}
215 \item{Wx::Image->new( stream, mimetype, index )}
216 \end{itemize}
217 }
218
219
220 \membersection{wxImage::\destruct{wxImage}}\label{wximagedtor}
221
222 \func{}{\destruct{wxImage}}{\void}
223
224 Destructor.
225
226
227 \membersection{wxImage::AddHandler}\label{wximageaddhandler}
228
229 \func{static void}{AddHandler}{\param{wxImageHandler*}{ handler}}
230
231 Adds a handler to the end of the static list of format handlers.
232
233 \docparam{handler}{A new image format handler object. There is usually only one instance
234 of a given handler class in an application session.}
235
236 \wxheading{See also}
237
238 \helpref{wxImageHandler}{wximagehandler}
239
240 \func{bool}{CanRead}{\param{const wxString\&}{ filename}}
241
242 returns true if the current image handlers can read this file
243
244 \pythonnote{In wxPython this static method is named {\tt wxImage\_AddHandler}.}
245
246 \membersection{wxImage::CleanUpHandlers}\label{wximagecleanuphandlers}
247
248 \func{static void}{CleanUpHandlers}{\void}
249
250 Deletes all image handlers.
251
252 This function is called by wxWidgets on exit.
253
254
255 \membersection{wxImage::ComputeHistogram}\label{wximagecomputehistogram}
256
257 \constfunc{unsigned long}{ComputeHistogram}{\param{wxImageHistogram\& }{histogram}}
258
259 Computes the histogram of the image. {\it histogram} is a reference to
260 wxImageHistogram object. wxImageHistogram is a specialization of
261 \helpref{wxHashMap}{wxhashmap} "template" and is defined as follows:
262
263 \begin{verbatim}
264 class WXDLLEXPORT wxImageHistogramEntry
265 {
266 public:
267 wxImageHistogramEntry() : index(0), value(0) {}
268 unsigned long index;
269 unsigned long value;
270 };
271
272 WX_DECLARE_EXPORTED_HASH_MAP(unsigned long, wxImageHistogramEntry,
273 wxIntegerHash, wxIntegerEqual,
274 wxImageHistogram);
275 \end{verbatim}
276
277 \wxheading{Return value}
278
279 Returns number of colours in the histogram.
280
281
282 \membersection{wxImage::ConvertAlphaToMask}\label{wximageconvertalphatomask}
283
284 \func{bool}{ConvertAlphaToMask}{\param{unsigned char}{ threshold = $128$}}
285
286 If the image has alpha channel, this method converts it to mask. All pixels
287 with alpha value less than \arg{threshold} are replaced with mask colour
288 and the alpha channel is removed. Mask colour is chosen automatically using
289 \helpref{FindFirstUnusedColour}{wximagefindfirstunusedcolour}.
290
291 If the image image doesn't have alpha channel,
292 ConvertAlphaToMask does nothing.
293
294 \wxheading{Return value}
295
296 \false if FindFirstUnusedColour returns \false, \true otherwise.
297
298
299 \membersection{wxImage::ConvertToBitmap}\label{wximageconverttobitmap}
300
301 \constfunc{wxBitmap}{ConvertToBitmap}{\void}
302
303 Deprecated, use equivalent \helpref{wxBitmap constructor}{wxbitmapctor}
304 (which takes wxImage and depth as its arguments) instead.
305
306
307 \membersection{wxImage::ConvertToGreyscale}\label{wximageconverttogreyscale}
308
309 \constfunc{wxImage}{ConvertToGreyscale}{\param{double}{ lr = 0.299}, \param{double}{ lg = 0.587}, \param{double}{ lb = 0.114}}
310
311 Returns a greyscale version of the image. The returned image uses the luminance
312 component of the original to calculate the greyscale. Defaults to using
313 ITU-T BT.601 when converting to YUV, where every pixel equals
314 (R * {\it lr}) + (G * {\it lg}) + (B * {\it lb}).
315
316
317 \membersection{wxImage::ConvertToMono}\label{wxbitmapconverttomono}
318
319 \constfunc{wxImage}{ConvertToMono}{\param{unsigned char}{ r}, \param{unsigned char}{ g}, \param{unsigned char}{ b}}
320
321 Returns monochromatic version of the image. The returned image has white
322 colour where the original has {\it (r,g,b)} colour and black colour
323 everywhere else.
324
325
326 \membersection{wxImage::Copy}\label{wximagecopy}
327
328 \constfunc{wxImage}{Copy}{\void}
329
330 Returns an identical copy of the image.
331
332
333 \membersection{wxImage::Create}\label{wximagecreate}
334
335 \func{bool}{Create}{\param{int}{ width}, \param{int}{ height}, \param{bool}{ clear=true}}
336
337 Creates a fresh image. If {\it clear} is true, the new image will be initialized to black.
338 Otherwise, the image data will be uninitialized.
339
340 \wxheading{Parameters}
341
342 \docparam{width}{The width of the image in pixels.}
343
344 \docparam{height}{The height of the image in pixels.}
345
346 \wxheading{Return value}
347
348 true if the call succeeded, false otherwise.
349
350
351 \membersection{wxImage::Destroy}\label{wximagedestroy}
352
353 \func{void}{Destroy}{\void}
354
355 Destroys the image data.
356
357
358 \membersection{wxImage::FindFirstUnusedColour}\label{wximagefindfirstunusedcolour}
359
360 \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}}
361
362 \wxheading{Parameters}
363
364 \docparam{r,g,b}{Pointers to variables to save the colour.}
365
366 \docparam{startR,startG,startB}{Initial values of the colour. Returned colour
367 will have RGB values equal to or greater than these.}
368
369 Finds the first colour that is never used in the image. The search begins at
370 given initial colour and continues by increasing R, G and B components (in this
371 order) by 1 until an unused colour is found or the colour space exhausted.
372
373 \wxheading{Return value}
374
375 Returns false if there is no unused colour left, true on success.
376
377 \wxheading{Notes}
378
379 Note that this method involves computing the histogram, which is
380 computationally intensive operation.
381
382
383 \membersection{wxImage::FindHandler}\label{wximagefindhandler}
384
385 \func{static wxImageHandler*}{FindHandler}{\param{const wxString\& }{name}}
386
387 Finds the handler with the given name.
388
389 \func{static wxImageHandler*}{FindHandler}{\param{const wxString\& }{extension}, \param{long}{ imageType}}
390
391 Finds the handler associated with the given extension and type.
392
393 \func{static wxImageHandler*}{FindHandler}{\param{long }{imageType}}
394
395 Finds the handler associated with the given image type.
396
397 \func{static wxImageHandler*}{FindHandlerMime}{\param{const wxString\& }{mimetype}}
398
399 Finds the handler associated with the given MIME type.
400
401 \docparam{name}{The handler name.}
402
403 \docparam{extension}{The file extension, such as ``bmp".}
404
405 \docparam{imageType}{The image type, such as wxBITMAP\_TYPE\_BMP.}
406
407 \docparam{mimetype}{MIME type.}
408
409 \wxheading{Return value}
410
411 A pointer to the handler if found, NULL otherwise.
412
413 \wxheading{See also}
414
415 \helpref{wxImageHandler}{wximagehandler}
416
417
418 \membersection{wxImage::GetImageExtWildcard}\label{wximagegetimageextwildcard}
419
420 \func{static wxString}{GetImageExtWildcard}{\void}
421
422 Iterates all registered wxImageHandler objects, and returns a string containing file extension masks
423 suitable for passing to file open/save dialog boxes.
424
425 \wxheading{Return value}
426
427 The format of the returned string is "(*.ext1;*.ext2)|*.ext1;*.ext2".
428
429 It is usually a good idea to prepend a description before passing the result to the dialog.
430
431 Example:
432
433 \begin{verbatim}
434 wxFileDialog FileDlg( this, "Choose Image", ::wxGetCwd(), "", _("Image Files ") + wxImage::GetImageExtWildcard(), wxOPEN );
435 \end{verbatim}
436
437 \wxheading{See also}
438
439 \helpref{wxImageHandler}{wximagehandler}
440
441
442 \membersection{wxImage::GetAlpha}\label{wximagegetalpha}
443
444 \constfunc{unsigned char}{GetAlpha}{\param{int}{ x}, \param{int}{ y}}
445
446 Returns the alpha value for the given pixel. This function may only be called
447 for the images with alpha channel, use \helpref{HasAlpha}{wximagehasalpha} to
448 check for this.
449
450 The returned value is the {\it opacity} of the image, i.e. the value of $0$
451 corresponds to the transparent pixels while the value of $255$ -- to the opaque
452 ones.
453
454 \constfunc{unsigned char *}{GetAlpha}{\void}
455
456 Returns pointer to the array storing the alpha values for this image. This
457 pointer is {\tt NULL} for the images without the alpha channel. If the image
458 does have it, this pointer may be used to directly manipulate the alpha values
459 which are stored as the \helpref{RGB}{wximagegetdata} ones.
460
461
462 \membersection{wxImage::GetBlue}\label{wximagegetblue}
463
464 \constfunc{unsigned char}{GetBlue}{\param{int}{ x}, \param{int}{ y}}
465
466 Returns the blue intensity at the given coordinate.
467
468
469 \membersection{wxImage::GetData}\label{wximagegetdata}
470
471 \constfunc{unsigned char*}{GetData}{\void}
472
473 Returns the image data as an array. This is most often used when doing
474 direct image manipulation. The return value points to an array of
475 characters in RGBRGBRGB$\ldots$ format in the top-to-bottom, left-to-right
476 order, that is the first RGB triplet corresponds to the pixel first pixel of
477 the first row, the second one --- to the second pixel of the first row and so
478 on until the end of the first row, with second row following after it and so
479 on.
480
481 You should not delete the returned pointer nor pass it to
482 \helpref{wxImage::SetData}{wximagesetdata}.
483
484
485 \membersection{wxImage::GetGreen}\label{wximagegetgreen}
486
487 \constfunc{unsigned char}{GetGreen}{\param{int}{ x}, \param{int}{ y}}
488
489 Returns the green intensity at the given coordinate.
490
491
492 \membersection{wxImage::GetImageCount}\label{wximagegetimagecount}
493
494 \func{static int}{GetImageCount}{\param{const wxString\&}{ filename}, \param{long}{ type = wxBITMAP\_TYPE\_ANY}}
495
496 \func{static int}{GetImageCount}{\param{wxInputStream\&}{ stream}, \param{long}{ type = wxBITMAP\_TYPE\_ANY}}
497
498 If the image file contains more than one image and the image handler is capable
499 of retrieving these individually, this function will return the number of
500 available images.
501
502 \docparam{name}{Name of the file to query.}
503
504 \docparam{stream}{Opened input stream with image data. Currently, the stream must support seeking.}
505
506 \docparam{type}{May be one of the following:
507
508 \twocolwidtha{5cm}%
509 \begin{twocollist}
510 \twocolitem{\indexit{wxBITMAP\_TYPE\_BMP}}{Load a Windows bitmap file.}
511 \twocolitem{\indexit{wxBITMAP\_TYPE\_GIF}}{Load a GIF bitmap file.}
512 \twocolitem{\indexit{wxBITMAP\_TYPE\_JPEG}}{Load a JPEG bitmap file.}
513 \twocolitem{\indexit{wxBITMAP\_TYPE\_PNG}}{Load a PNG bitmap file.}
514 \twocolitem{\indexit{wxBITMAP\_TYPE\_PCX}}{Load a PCX bitmap file.}
515 \twocolitem{\indexit{wxBITMAP\_TYPE\_PNM}}{Load a PNM bitmap file.}
516 \twocolitem{\indexit{wxBITMAP\_TYPE\_TIF}}{Load a TIFF bitmap file.}
517 \twocolitem{\indexit{wxBITMAP\_TYPE\_XPM}}{Load a XPM bitmap file.}
518 \twocolitem{\indexit{wxBITMAP\_TYPE\_ICO}}{Load a Windows icon file (ICO).}
519 \twocolitem{\indexit{wxBITMAP\_TYPE\_CUR}}{Load a Windows cursor file (CUR).}
520 \twocolitem{\indexit{wxBITMAP\_TYPE\_ANI}}{Load a Windows animated cursor file (ANI).}
521 \twocolitem{\indexit{wxBITMAP\_TYPE\_ANY}}{Will try to autodetect the format.}
522 \end{twocollist}}
523
524 \wxheading{Return value}
525
526 Number of available images. For most image handlers, this is 1 (exceptions
527 are TIFF and ICO formats).
528
529
530 \membersection{wxImage::GetHandlers}\label{wximagegethandlers}
531
532 \func{static wxList\&}{GetHandlers}{\void}
533
534 Returns the static list of image format handlers.
535
536 \wxheading{See also}
537
538 \helpref{wxImageHandler}{wximagehandler}
539
540
541 \membersection{wxImage::GetHeight}\label{wximagegetheight}
542
543 \constfunc{int}{GetHeight}{\void}
544
545 Gets the height of the image in pixels.
546
547
548 \membersection{wxImage::GetMaskBlue}\label{wximagegetmaskblue}
549
550 \constfunc{unsigned char}{GetMaskBlue}{\void}
551
552 Gets the blue value of the mask colour.
553
554
555 \membersection{wxImage::GetMaskGreen}\label{wximagegetmaskgreen}
556
557 \constfunc{unsigned char}{GetMaskGreen}{\void}
558
559 Gets the green value of the mask colour.
560
561
562 \membersection{wxImage::GetMaskRed}\label{wximagegetmaskred}
563
564 \constfunc{unsigned char}{GetMaskRed}{\void}
565
566 Gets the red value of the mask colour.
567
568
569 \membersection{wxImage::GetOrFindMaskColour}\label{wximagegetgetorsetmaskcolour}
570
571 \constfunc{bool}{GetOrFindMaskColour}{\param{unsigned char}{ *r}, \param{unsigned char}{ *g}, \param{unsigned char}{ *b}}
572
573 Get the current mask colour or find a suitable unused colour that could be
574 used as a mask colour. Returns {\tt true} if the image currently has a mask.
575
576
577 \membersection{wxImage::GetPalette}\label{wximagegetpalette}
578
579 \constfunc{const wxPalette\&}{GetPalette}{\void}
580
581 Returns the palette associated with the image. Currently the palette is only
582 used when converting to wxBitmap under Windows.
583
584 Eventually wxImage handlers will set the palette if one exists in the image file.
585
586
587 \membersection{wxImage::GetRed}\label{wximagegetred}
588
589 \constfunc{unsigned char}{GetRed}{\param{int}{ x}, \param{int}{ y}}
590
591 Returns the red intensity at the given coordinate.
592
593
594 \membersection{wxImage::GetSubImage}\label{wximagegetsubimage}
595
596 \constfunc{wxImage}{GetSubImage}{\param{const wxRect\&}{ rect}}
597
598 Returns a sub image of the current one as long as the rect belongs entirely to
599 the image.
600
601
602 \membersection{wxImage::GetWidth}\label{wximagegetwidth}
603
604 \constfunc{int}{GetWidth}{\void}
605
606 Gets the width of the image in pixels.
607
608 \wxheading{See also}
609
610 \helpref{wxImage::GetHeight}{wximagegetheight}
611
612
613 \membersection{HSVValue::HSVValue}\label{hsvvaluehsvvalue}
614
615 \func{}{HSVValue}{\param{double }{h = 0.0}, \param{double }{s = 0.0}, \param{double }{v = 0.0}}
616
617 Constructor for HSVValue, an object that contains values for hue, saturation and value which
618 represent the value of a color. It is used by \helpref{wxImage::HSVtoRGB}{wximagehsvtorgb}
619 and \helpref{wxImage::RGBtoHSV}{wximagergbtohsv}, which
620 converts between HSV color space and RGB color space.
621
622 \pythonnote{use wxImage\_HSVValue in wxPython}
623
624
625
626 \membersection{wxImage::HSVtoRGB}\label{wximagehsvtorgb}
627
628 \func{wxImage::RGBValue}{HSVtoRGB}{\param{const HSVValue \& }{hsv}}
629
630 Converts a color in HSV color space to RGB color space.
631
632
633 \membersection{wxImage::HasAlpha}\label{wximagehasalpha}
634
635 \constfunc{bool}{HasAlpha}{\void}
636
637 Returns true if this image has alpha channel, false otherwise.
638
639 \wxheading{See also}
640
641 \helpref{GetAlpha}{wximagegetalpha}, \helpref{SetAlpha}{wximagesetalpha}
642
643
644 \membersection{wxImage::HasMask}\label{wximagehasmask}
645
646 \constfunc{bool}{HasMask}{\void}
647
648 Returns true if there is a mask active, false otherwise.
649
650
651 \membersection{wxImage::GetOption}\label{wximagegetoption}
652
653 \constfunc{wxString}{GetOption}{\param{const wxString\&}{ name}}
654
655 Gets a user-defined option. The function is case-insensitive to {\it name}.
656
657 For example, when saving as a JPEG file, the option {\bf quality} is
658 used, which is a number between 0 and 100 (0 is terrible, 100 is very good).
659
660 \wxheading{See also}
661
662 \helpref{wxImage::SetOption}{wximagesetoption},\rtfsp
663 \helpref{wxImage::GetOptionInt}{wximagegetoptionint},\rtfsp
664 \helpref{wxImage::HasOption}{wximagehasoption}
665
666
667 \membersection{wxImage::GetOptionInt}\label{wximagegetoptionint}
668
669 \constfunc{int}{GetOptionInt}{\param{const wxString\&}{ name}}
670
671 Gets a user-defined option as an integer. The function is case-insensitive to {\it name}.
672
673 If the given option is not present, the function returns $0$. Use
674 \helpref{wxImage::HasOption}{wximagehasoption} is $0$ is a possibly valid value
675 for the option.
676
677 Options for wxPNGHandler
678 \twocolwidtha{5cm}%
679 \begin{twocollist}
680 \twocolitem{wxIMAGE\_OPTION\_PNG\_FORMAT}{Format for saving a PNG file.}
681 \twocolitem{wxIMAGE\_OPTION\_PNG\_BITDEPTH}{Bit depth for every channel (R/G/B/A).}
682 \end{twocollist}
683
684 Supported values for wxIMAGE\_OPTION\_PNG\_FORMAT:
685 \twocolwidtha{5cm}%
686 \begin{twocollist}
687 \twocolitem{wxPNG\_TYPE\_COLOUR}{Stores RGB image.}
688 \twocolitem{wxPNG\_TYPE\_GREY}{Stores grey image, converts from RGB.}
689 \twocolitem{wxPNG\_TYPE\_GREY\_RED}{Stores grey image, uses red value as grey.}
690 \end{twocollist}
691
692
693 \wxheading{See also}
694
695 \helpref{wxImage::SetOption}{wximagesetoption},\rtfsp
696 \helpref{wxImage::GetOption}{wximagegetoption}
697
698
699 \membersection{wxImage::HasOption}\label{wximagehasoption}
700
701 \constfunc{bool}{HasOption}{\param{const wxString\&}{ name}}
702
703 Returns true if the given option is present. The function is case-insensitive to {\it name}.
704
705 \wxheading{See also}
706
707 \helpref{wxImage::SetOption}{wximagesetoption},\rtfsp
708 \helpref{wxImage::GetOption}{wximagegetoption},\rtfsp
709 \helpref{wxImage::GetOptionInt}{wximagegetoptionint}
710
711
712 \membersection{wxImage::InitAlpha}\label{wximageinitalpha}
713
714 \func{void}{InitAlpha}{\void}
715
716 Initializes the image alpha channel data. It is an error to call it
717 if the image already has alpha data. If it doesn't, alpha data will be
718 by default initialized to all pixels being fully opaque. But if the image has a
719 a mask colour, all mask pixels will be completely transparent.
720
721
722 \membersection{wxImage::InitStandardHandlers}\label{wximageinitstandardhandlers}
723
724 \func{static void}{InitStandardHandlers}{\void}
725
726 Internal use only. Adds standard image format handlers. It only install BMP
727 for the time being, which is used by wxBitmap.
728
729 This function is called by wxWidgets on startup, and shouldn't be called by
730 the user.
731
732 \wxheading{See also}
733
734 \helpref{wxImageHandler}{wximagehandler},
735 \helpref{wxInitAllImageHandlers}{wxinitallimagehandlers}
736
737
738 \membersection{wxImage::InsertHandler}\label{wximageinserthandler}
739
740 \func{static void}{InsertHandler}{\param{wxImageHandler*}{ handler}}
741
742 Adds a handler at the start of the static list of format handlers.
743
744 \docparam{handler}{A new image format handler object. There is usually only one instance
745 of a given handler class in an application session.}
746
747 \wxheading{See also}
748
749 \helpref{wxImageHandler}{wximagehandler}
750
751
752 \membersection{wxImage::IsTransparent}\label{wximageistransparent}
753
754 \constfunc{bool}{IsTransparent}{\param{int }{x}, \param{int }{y}, \param{unsigned char}{ threshold = $128$}}
755
756 Returns \true if the given pixel is transparent, i.e. either has the mask
757 colour if this image has a mask or if this image has alpha channel and alpha
758 value of this pixel is strictly less than \arg{threshold}.
759
760
761 \membersection{wxImage::LoadFile}\label{wximageloadfile}
762
763 \func{bool}{LoadFile}{\param{const wxString\&}{ name}, \param{long}{ type = wxBITMAP\_TYPE\_ANY}, \param{int}{ index = -1}}
764
765 \func{bool}{LoadFile}{\param{const wxString\&}{ name}, \param{const wxString\&}{ mimetype}, \param{int}{ index = -1}}
766
767 Loads an image from a file. If no handler type is provided, the library will
768 try to autodetect the format.
769
770 \func{bool}{LoadFile}{\param{wxInputStream\&}{ stream}, \param{long}{ type}, \param{int}{ index = -1}}
771
772 \func{bool}{LoadFile}{\param{wxInputStream\&}{ stream}, \param{const wxString\&}{ mimetype}, \param{int}{ index = -1}}
773
774 Loads an image from an input stream.
775
776 \wxheading{Parameters}
777
778 \docparam{name}{Name of the file from which to load the image.}
779
780 \docparam{stream}{Opened input stream from which to load the image. Currently, the stream must support seeking.}
781
782 \docparam{type}{One of the following values:
783
784 \twocolwidtha{5cm}%
785 \begin{twocollist}
786 \twocolitem{{\bf wxBITMAP\_TYPE\_BMP}}{Load a Windows image file.}
787 \twocolitem{{\bf wxBITMAP\_TYPE\_GIF}}{Load a GIF image file.}
788 \twocolitem{{\bf wxBITMAP\_TYPE\_JPEG}}{Load a JPEG image file.}
789 \twocolitem{{\bf wxBITMAP\_TYPE\_PCX}}{Load a PCX image file.}
790 \twocolitem{{\bf wxBITMAP\_TYPE\_PNG}}{Load a PNG image file.}
791 \twocolitem{{\bf wxBITMAP\_TYPE\_PNM}}{Load a PNM image file.}
792 \twocolitem{{\bf wxBITMAP\_TYPE\_TIF}}{Load a TIFF image file.}
793 \twocolitem{{\bf wxBITMAP\_TYPE\_XPM}}{Load a XPM image file.}
794 \twocolitem{{\bf wxBITMAP\_TYPE\_ICO}}{Load a Windows icon file (ICO).}
795 \twocolitem{{\bf wxBITMAP\_TYPE\_CUR}}{Load a Windows cursor file (CUR).}
796 \twocolitem{\indexit{wxBITMAP\_TYPE\_ANI}}{Load a Windows animated cursor file (ANI).}
797 \twocolitem{{\bf wxBITMAP\_TYPE\_ANY}}{Will try to autodetect the format.}
798 \end{twocollist}}
799
800 \docparam{mimetype}{MIME type string (for example 'image/jpeg')}
801
802 \docparam{index}{Index of the image to load in the case that the image file contains multiple images.
803 This is only used by GIF, ICO and TIFF handlers. The default value (-1) means
804 "choose the default image" and is interpreted as the first image (index=0) by
805 the GIF and TIFF handler and as the largest and most colourful one by the ICO handler.}
806
807 \wxheading{Remarks}
808
809 Depending on how wxWidgets has been configured, not all formats may be available.
810
811 Note: you can use \helpref{GetOptionInt}{wximagegetoptionint} to get the
812 hotspot for loaded cursor file:
813 \begin{verbatim}
814 int hotspot_x = image.GetOptionInt(wxIMAGE_OPTION_CUR_HOTSPOT_X);
815 int hotspot_y = image.GetOptionInt(wxIMAGE_OPTION_CUR_HOTSPOT_Y);
816
817 \end{verbatim}
818
819 \wxheading{Return value}
820
821 true if the operation succeeded, false otherwise. If the optional index parameter is out of range,
822 false is returned and a call to wxLogError() takes place.
823
824 \wxheading{See also}
825
826 \helpref{wxImage::SaveFile}{wximagesavefile}
827
828 \pythonnote{In place of a single overloaded method name, wxPython
829 implements the following methods:\par
830 \indented{2cm}{\begin{twocollist}
831 \twocolitem{{\bf LoadFile(filename, type)}}{Loads an image of the given
832 type from a file}
833 \twocolitem{{\bf LoadMimeFile(filename, mimetype)}}{Loads an image of the given
834 mimetype from a file}
835 \end{twocollist}}
836 }
837
838 \perlnote{Methods supported by wxPerl are:\par
839 \begin{itemize}
840 \item{bitmap->LoadFile( name, type )}
841 \item{bitmap->LoadFile( name, mimetype )}
842 \end{itemize}
843 }
844
845
846
847 \membersection{wxImage::Ok}\label{wximageok}
848
849 \constfunc{bool}{Ok}{\void}
850
851 Returns true if image data is present.
852
853
854 \membersection{RGBValue::RGBValue}\label{rgbvaluergbvalue}
855
856 \func{}{RGBValue}{\param{unsigned char }{r = 0}, \param{unsigned char }{g = 0}, \param{unsigned char }{b = 0}}
857
858 Constructor for RGBValue, an object that contains values for red, green and blud which
859 represent the value of a color. It is used by \helpref{wxImage::HSVtoRGB}{wximagehsvtorgb}
860 and \helpref{wxImage::RGBtoHSV}{wximagergbtohsv}, which
861 converts between HSV color space and RGB color space.
862
863 \pythonnote{use wxImage\_RGBValue in wxPython}
864
865
866 \membersection{wxImage::RGBtoHSV}\label{wximagergbtohsv}
867
868 \func{wxImage::HSVValue}{RGBtoHSV}{\param{const RGBValue\& }{rgb}}
869
870 Converts a color in RGB color space to HSV color space.
871
872
873 \membersection{wxImage::RemoveHandler}\label{wximageremovehandler}
874
875 \func{static bool}{RemoveHandler}{\param{const wxString\& }{name}}
876
877 Finds the handler with the given name, and removes it. The handler
878 is not deleted.
879
880 \docparam{name}{The handler name.}
881
882 \wxheading{Return value}
883
884 true if the handler was found and removed, false otherwise.
885
886 \wxheading{See also}
887
888 \helpref{wxImageHandler}{wximagehandler}
889
890
891 \membersection{wxImage::Mirror}\label{wximagemirror}
892
893 \constfunc{wxImage}{Mirror}{\param{bool}{ horizontally = true}}
894
895 Returns a mirrored copy of the image. The parameter {\it horizontally}
896 indicates the orientation.
897
898
899 \membersection{wxImage::Replace}\label{wximagereplace}
900
901 \func{void}{Replace}{\param{unsigned char}{ r1}, \param{unsigned char}{ g1}, \param{unsigned char}{ b1},
902 \param{unsigned char}{ r2}, \param{unsigned char}{ g2}, \param{unsigned char}{ b2}}
903
904 Replaces the colour specified by {\it r1,g1,b1} by the colour {\it r2,g2,b2}.
905
906
907 \membersection{wxImage::Rescale}\label{wximagerescale}
908
909 \func{wxImage \&}{Rescale}{\param{int}{ width}, \param{int}{ height}}
910
911 Changes the size of the image in-place by scaling it: after a call to this function,
912 the image will have the given width and height.
913
914 Returns the (modified) image itself.
915
916 \wxheading{See also}
917
918 \helpref{Scale}{wximagescale}
919
920
921 \membersection{wxImage::Resize}\label{wximageresize}
922
923 \func{wxImage \&}{Resize}{\param{const wxSize\&}{ size}, \param{const wxPoint&}{ pos}, \param{int}{ red = -1}, \param{int}{ green = -1}, \param{int}{ blue = -1}}
924
925 Changes the size of the image in-place without scaling it by adding either a border
926 with the given colour or cropping as necessary. The image is pasted into a new
927 image with the given {\it size} and background colour at the position {\it pos}
928 relative to the upper left of the new image. If {\it red = green = blue = -1}
929 then use either the current mask colour if set or find, use, and set a
930 suitable mask colour for any newly exposed areas.
931
932 Returns the (modified) image itself.
933
934 \wxheading{See also}
935
936 \helpref{Size}{wximagesize}
937
938
939 \membersection{wxImage::Rotate}\label{wximagerotate}
940
941 \func{wxImage}{Rotate}{\param{double}{ angle}, \param{const wxPoint\& }{rotationCentre},
942 \param{bool}{ interpolating = true}, \param{wxPoint*}{ offsetAfterRotation = NULL}}
943
944 Rotates the image about the given point, by {\it angle} radians. Passing true
945 to {\it interpolating} results in better image quality, but is slower. If the
946 image has a mask, then the mask colour is used for the uncovered pixels in the
947 rotated image background. Else, black (rgb 0, 0, 0) will be used.
948
949 Returns the rotated image, leaving this image intact.
950
951
952 \membersection{wxImage::RotateHue}\label{wximagerotatehue}
953
954 \func{void}{RotateHue}{\param{double}{ angle}}
955
956 Rotates the hue of each pixel in the image by {\it angle}, which is a double in
957 the range of -1.0 to +1.0, where -1.0 corresponds to -360 degrees and +1.0 corresponds
958 to +360 degrees.
959
960
961 \membersection{wxImage::Rotate90}\label{wximagerotate90}
962
963 \constfunc{wxImage}{Rotate90}{\param{bool}{ clockwise = true}}
964
965 Returns a copy of the image rotated 90 degrees in the direction
966 indicated by {\it clockwise}.
967
968
969 \membersection{wxImage::SaveFile}\label{wximagesavefile}
970
971 \constfunc{bool}{SaveFile}{\param{const wxString\& }{name}, \param{int}{ type}}
972
973 \constfunc{bool}{SaveFile}{\param{const wxString\& }{name}, \param{const wxString\&}{ mimetype}}
974
975 Saves an image in the named file.
976
977 \constfunc{bool}{SaveFile}{\param{const wxString\& }{name}}
978
979 Saves an image in the named file. File type is determined from the extension of the
980 file name. Note that this function may fail if the extension is not recognized! You
981 can use one of the forms above to save images to files with non-standard extensions.
982
983 \constfunc{bool}{SaveFile}{\param{wxOutputStream\& }{stream}, \param{int}{ type}}
984
985 \constfunc{bool}{SaveFile}{\param{wxOutputStream\& }{stream}, \param{const wxString\&}{ mimetype}}
986
987 Saves an image in the given stream.
988
989 \wxheading{Parameters}
990
991 \docparam{name}{Name of the file to save the image to.}
992
993 \docparam{stream}{Opened output stream to save the image to.}
994
995 \docparam{type}{Currently these types can be used:
996
997 \twocolwidtha{5cm}%
998 \begin{twocollist}
999 \twocolitem{{\bf wxBITMAP\_TYPE\_BMP}}{Save a BMP image file.}
1000 \twocolitem{{\bf wxBITMAP\_TYPE\_JPEG}}{Save a JPEG image file.}
1001 \twocolitem{{\bf wxBITMAP\_TYPE\_PNG}}{Save a PNG image file.}
1002 \twocolitem{{\bf wxBITMAP\_TYPE\_PCX}}{Save a PCX image file (tries to save as 8-bit if possible, falls back to 24-bit otherwise).}
1003 \twocolitem{{\bf wxBITMAP\_TYPE\_PNM}}{Save a PNM image file (as raw RGB always).}
1004 \twocolitem{{\bf wxBITMAP\_TYPE\_TIFF}}{Save a TIFF image file.}
1005 \twocolitem{{\bf wxBITMAP\_TYPE\_XPM}}{Save a XPM image file.}
1006 \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).}
1007 \twocolitem{{\bf wxBITMAP\_TYPE\_CUR}}{Save a Windows cursor file (CUR).}
1008 \end{twocollist}}
1009
1010 \docparam{mimetype}{MIME type.}
1011
1012 \wxheading{Return value}
1013
1014 true if the operation succeeded, false otherwise.
1015
1016 \wxheading{Remarks}
1017
1018 Depending on how wxWidgets has been configured, not all formats may be available.
1019
1020 Note: you can use \helpref{GetOptionInt}{wximagegetoptionint} to set the
1021 hotspot before saving an image into a cursor file (default hotspot is in
1022 the centre of the image):
1023 \begin{verbatim}
1024 image.SetOption(wxIMAGE_OPTION_CUR_HOTSPOT_X, hotspotX);
1025 image.SetOption(wxIMAGE_OPTION_CUR_HOTSPOT_Y, hotspotY);
1026
1027 \end{verbatim}
1028
1029 \wxheading{See also}
1030
1031 \helpref{wxImage::LoadFile}{wximageloadfile}
1032
1033 \pythonnote{In place of a single overloaded method name, wxPython
1034 implements the following methods:\par
1035 \indented{2cm}{\begin{twocollist}
1036 \twocolitem{{\bf SaveFile(filename, type)}}{Saves the image using the given
1037 type to the named file}
1038 \twocolitem{{\bf SaveMimeFile(filename, mimetype)}}{Saves the image using the given
1039 mimetype to the named file}
1040 \end{twocollist}}
1041 }
1042
1043 \perlnote{Methods supported by wxPerl are:\par
1044 \begin{itemize}
1045 \item{bitmap->SaveFile( name, type )}
1046 \item{bitmap->SaveFile( name, mimetype )}
1047 \end{itemize}
1048 }
1049
1050
1051 \membersection{wxImage::Scale}\label{wximagescale}
1052
1053 \constfunc{wxImage}{Scale}{\param{int}{ width}, \param{int}{ height}}
1054
1055 Returns a scaled version of the image. This is also useful for
1056 scaling bitmaps in general as the only other way to scale bitmaps
1057 is to blit a wxMemoryDC into another wxMemoryDC.
1058
1059 It may be mentioned that the GTK port uses this function internally
1060 to scale bitmaps when using mapping modes in wxDC.
1061
1062 Example:
1063
1064 \begin{verbatim}
1065 // get the bitmap from somewhere
1066 wxBitmap bmp = ...;
1067
1068 // rescale it to have size of 32*32
1069 if ( bmp.GetWidth() != 32 || bmp.GetHeight() != 32 )
1070 {
1071 wxImage image = bmp.ConvertToImage();
1072 bmp = wxBitmap(image.Scale(32, 32));
1073
1074 // another possibility:
1075 image.Rescale(32, 32);
1076 bmp = image;
1077 }
1078
1079 \end{verbatim}
1080
1081 \wxheading{See also}
1082
1083 \helpref{Rescale}{wximagerescale}
1084
1085
1086 \membersection{wxImage::Size}\label{wximagesize}
1087
1088 \constfunc{wxImage}{Size}{\param{const wxSize\&}{ size}, \param{const wxPoint&}{ pos}, \param{int}{ red = -1}, \param{int}{ green = -1}, \param{int}{ blue = -1}}
1089
1090 Returns a resized version of this image without scaling it by adding either a border
1091 with the given colour or cropping as necessary. The image is pasted into a new
1092 image with the given {\it size} and background colour at the position {\it pos}
1093 relative to the upper left of the new image. If {\it red = green = blue = -1}
1094 then use either the current mask colour if set or find, use, and set a
1095 suitable mask colour for any newly exposed areas.
1096
1097 \wxheading{See also}
1098
1099 \helpref{Resize}{wximageresize}
1100
1101
1102 \membersection{wxImage::SetAlpha}\label{wximagesetalpha}
1103
1104 \func{void}{SetAlpha}{\param{unsigned char *}{alpha = {\tt NULL}},\param{bool}{ static\_data = \false}}
1105
1106 This function is similar to \helpref{SetData}{wximagesetdata} and has similar
1107 restrictions. The pointer passed to it may however be {\tt NULL} in which case
1108 the function will allocate the alpha array internally -- this is useful to add
1109 alpha channel data to an image which doesn't have any. If the pointer is not
1110 {\tt NULL}, it must have one byte for each image pixel and be allocated with
1111 {\tt malloc()}. wxImage takes ownership of the pointer and will free it unless
1112 \arg{static\_data} parameter is set to \true -- in this case the caller should
1113 do it.
1114
1115 \func{void}{SetAlpha}{\param{int }{x}, \param{int }{y}, \param{unsigned char }{alpha}}
1116
1117 Sets the alpha value for the given pixel. This function should only be called
1118 if the image has alpha channel data, use \helpref{HasAlpha}{wximagehasalpha} to
1119 check for this.
1120
1121
1122 \membersection{wxImage::SetData}\label{wximagesetdata}
1123
1124 \func{void}{SetData}{\param{unsigned char*}{data}}
1125
1126 Sets the image data without performing checks. The data given must have
1127 the size (width*height*3) or results will be unexpected. Don't use this
1128 method if you aren't sure you know what you are doing.
1129
1130 The data must have been allocated with {\tt malloc()}, {\large {\bf NOT}} with
1131 {\tt operator new}.
1132
1133 After this call the pointer to the data is owned by the wxImage object,
1134 that will be responsible for deleting it.
1135 Do not pass to this function a pointer obtained through
1136 \helpref{wxImage::GetData}{wximagegetdata}.
1137
1138
1139 \membersection{wxImage::SetMask}\label{wximagesetmask}
1140
1141 \func{void}{SetMask}{\param{bool}{ hasMask = true}}
1142
1143 Specifies whether there is a mask or not. The area of the mask is determined by the current mask colour.
1144
1145
1146 \membersection{wxImage::SetMaskColour}\label{wximagesetmaskcolour}
1147
1148 \func{void}{SetMaskColour}{\param{unsigned char }{red}, \param{unsigned char }{green}, \param{unsigned char }{blue}}
1149
1150 Sets the mask colour for this image (and tells the image to use the mask).
1151
1152
1153 \membersection{wxImage::SetMaskFromImage}\label{wximagesetmaskfromimage}
1154
1155 \func{bool}{SetMaskFromImage}{\param{const wxImage\&}{ mask}, \param{unsigned char}{ mr}, \param{unsigned char}{ mg}, \param{unsigned char}{ mb}}
1156
1157 \wxheading{Parameters}
1158
1159 \docparam{mask}{The mask image to extract mask shape from. Must have same dimensions as the image.}
1160
1161 \docparam{mr,mg,mb}{RGB value of pixels in {\it mask} that will be used to create the mask.}
1162
1163 Sets image's mask so that the pixels that have RGB value of {\it mr,mg,mb}
1164 in {\it mask} will be masked in the image. This is done by first finding an
1165 unused colour in the image, setting this colour as the mask colour and then
1166 using this colour to draw all pixels in the image who corresponding pixel
1167 in {\it mask} has given RGB value.
1168
1169 \wxheading{Return value}
1170
1171 Returns false if {\it mask} does not have same dimensions as the image or if
1172 there is no unused colour left. Returns true if the mask was successfully
1173 applied.
1174
1175 \wxheading{Notes}
1176
1177 Note that this method involves computing the histogram, which is
1178 computationally intensive operation.
1179
1180
1181 \membersection{wxImage::SetOption}\label{wximagesetoption}
1182
1183 \func{void}{SetOption}{\param{const wxString\&}{ name}, \param{const wxString\&}{ value}}
1184
1185 \func{void}{SetOption}{\param{const wxString\&}{ name}, \param{int}{ value}}
1186
1187 Sets a user-defined option. The function is case-insensitive to {\it name}.
1188
1189 For example, when saving as a JPEG file, the option {\bf quality} is
1190 used, which is a number between 0 and 100 (0 is terrible, 100 is very good).
1191
1192 \wxheading{See also}
1193
1194 \helpref{wxImage::GetOption}{wximagegetoption},\rtfsp
1195 \helpref{wxImage::GetOptionInt}{wximagegetoptionint},\rtfsp
1196 \helpref{wxImage::HasOption}{wximagehasoption}
1197
1198
1199 \membersection{wxImage::SetPalette}\label{wximagesetpalette}
1200
1201 \func{void}{SetPalette}{\param{const wxPalette\&}{ palette}}
1202
1203 Associates a palette with the image. The palette may be used when converting
1204 wxImage to wxBitmap (MSW only at present) or in file save operations (none as yet).
1205
1206
1207 \membersection{wxImage::SetRGB}\label{wximagesetrgb}
1208
1209 \func{void}{SetRGB}{\param{int }{x}, \param{int }{y}, \param{unsigned char }{red}, \param{unsigned char }{green}, \param{unsigned char }{blue}}
1210
1211 Sets the pixel at the given coordinate. This routine performs bounds-checks
1212 for the coordinate so it can be considered a safe way to manipulate the
1213 data, but in some cases this might be too slow so that the data will have to
1214 be set directly. In that case you will have to get access to the image data
1215 using the \helpref{GetData}{wximagegetdata} method.
1216
1217
1218 \membersection{wxImage::SetRGB}\label{wximagesetrgbrect}
1219
1220 \func{void}{SetRGB}{\param{wxRect \& }{rect}, \param{unsigned char }{red}, \param{unsigned char }{green}, \param{unsigned char }{blue}}
1221
1222 Sets the colour of the pixels within the given rectangle. This routine performs
1223 bounds-checks for the coordinate so it can be considered a safe way to manipulate the
1224 data.
1225
1226
1227 \membersection{wxImage::operator $=$}\label{wximageassign}
1228
1229 \func{wxImage\& }{operator $=$}{\param{const wxImage\& }{image}}
1230
1231 Assignment operator. This operator does not copy any data, but instead
1232 passes a pointer to the data in {\it image} and increments a reference
1233 counter. It is a fast operation.
1234
1235 \wxheading{Parameters}
1236
1237 \docparam{image}{Image to assign.}
1238
1239 \wxheading{Return value}
1240
1241 Returns 'this' object.
1242
1243
1244 \membersection{wxImage::operator $==$}\label{wximageequal}
1245
1246 \constfunc{bool}{operator $==$}{\param{const wxImage\& }{image}}
1247
1248 Equality operator. This operator tests whether the internal data pointers are
1249 equal (a fast test).
1250
1251 \wxheading{Parameters}
1252
1253 \docparam{image}{Image to compare with 'this'}
1254
1255 \wxheading{Return value}
1256
1257 Returns true if the images were effectively equal, false otherwise.
1258
1259
1260 \membersection{wxImage::operator $!=$}\label{wximagenotequal}
1261
1262 \constfunc{bool}{operator $!=$}{\param{const wxImage\& }{image}}
1263
1264 Inequality operator. This operator tests whether the internal data pointers are
1265 unequal (a fast test).
1266
1267 \wxheading{Parameters}
1268
1269 \docparam{image}{Image to compare with 'this'}
1270
1271 \wxheading{Return value}
1272
1273 Returns true if the images were unequal, false otherwise.
1274
1275 \section{\class{wxImageHandler}}\label{wximagehandler}
1276
1277 This is the base class for implementing image file loading/saving, and image creation from data.
1278 It is used within wxImage and is not normally seen by the application.
1279
1280 If you wish to extend the capabilities of wxImage, derive a class from wxImageHandler
1281 and add the handler using \helpref{wxImage::AddHandler}{wximageaddhandler} in your
1282 application initialisation.
1283
1284 \wxheading{Note (Legal Issue)}
1285
1286 This software is based in part on the work of the Independent JPEG Group.
1287
1288 (Applies when wxWidgets is linked with JPEG support. wxJPEGHandler uses libjpeg
1289 created by IJG.)
1290
1291 \wxheading{Derived from}
1292
1293 \helpref{wxObject}{wxobject}
1294
1295 \wxheading{Include files}
1296
1297 <wx/image.h>
1298
1299 \wxheading{See also}
1300
1301 \helpref{wxImage}{wximage},
1302 \helpref{wxInitAllImageHandlers}{wxinitallimagehandlers}
1303
1304 \latexignore{\rtfignore{\wxheading{Members}}}
1305
1306
1307 \membersection{wxImageHandler::wxImageHandler}\label{wximagehandlerctor}
1308
1309 \func{}{wxImageHandler}{\void}
1310
1311 Default constructor. In your own default constructor, initialise the members
1312 m\_name, m\_extension and m\_type.
1313
1314
1315 \membersection{wxImageHandler::\destruct{wxImageHandler}}\label{wximagehandlerdtor}
1316
1317 \func{}{\destruct{wxImageHandler}}{\void}
1318
1319 Destroys the wxImageHandler object.
1320
1321
1322 \membersection{wxImageHandler::GetName}\label{wximagehandlergetname}
1323
1324 \constfunc{wxString}{GetName}{\void}
1325
1326 Gets the name of this handler.
1327
1328
1329 \membersection{wxImageHandler::GetExtension}\label{wximagehandlergetextension}
1330
1331 \constfunc{wxString}{GetExtension}{\void}
1332
1333 Gets the file extension associated with this handler.
1334
1335
1336 \membersection{wxImageHandler::GetImageCount}\label{wximagehandlergetimagecount}
1337
1338 \func{int}{GetImageCount}{\param{wxInputStream\&}{ stream}}
1339
1340 If the image file contains more than one image and the image handler is capable
1341 of retrieving these individually, this function will return the number of
1342 available images.
1343
1344 \docparam{stream}{Opened input stream for reading image data. Currently, the stream must support seeking.}
1345
1346 \wxheading{Return value}
1347
1348 Number of available images. For most image handlers, this is 1 (exceptions
1349 are TIFF and ICO formats).
1350
1351
1352 \membersection{wxImageHandler::GetType}\label{wximagehandlergettype}
1353
1354 \constfunc{long}{GetType}{\void}
1355
1356 Gets the image type associated with this handler.
1357
1358
1359 \membersection{wxImageHandler::GetMimeType}\label{wximagehandlergetmimetype}
1360
1361 \constfunc{wxString}{GetMimeType}{\void}
1362
1363 Gets the MIME type associated with this handler.
1364
1365
1366 \membersection{wxImageHandler::LoadFile}\label{wximagehandlerloadfile}
1367
1368 \func{bool}{LoadFile}{\param{wxImage* }{image}, \param{wxInputStream\&}{ stream}, \param{bool}{ verbose=true}, \param{int}{ index=0}}
1369
1370 Loads a image from a stream, putting the resulting data into {\it image}. If the image file contains
1371 more than one image and the image handler is capable of retrieving these individually, {\it index}
1372 indicates which image to read from the stream.
1373
1374 \wxheading{Parameters}
1375
1376 \docparam{image}{The image object which is to be affected by this operation.}
1377
1378 \docparam{stream}{Opened input stream for reading image data.}
1379
1380 \docparam{verbose}{If set to true, errors reported by the image handler will produce wxLogMessages.}
1381
1382 \docparam{index}{The index of the image in the file (starting from zero).}
1383
1384 \wxheading{Return value}
1385
1386 true if the operation succeeded, false otherwise.
1387
1388 \wxheading{See also}
1389
1390 \helpref{wxImage::LoadFile}{wximageloadfile},
1391 \helpref{wxImage::SaveFile}{wximagesavefile},
1392 \helpref{wxImageHandler::SaveFile}{wximagehandlersavefile}
1393
1394
1395 \membersection{wxImageHandler::SaveFile}\label{wximagehandlersavefile}
1396
1397 \func{bool}{SaveFile}{\param{wxImage* }{image}, \param{wxOutputStream\& }{stream}}
1398
1399 Saves a image in the output stream.
1400
1401 \wxheading{Parameters}
1402
1403 \docparam{image}{The image object which is to be affected by this operation.}
1404
1405 \docparam{stream}{Opened output stream for writing the data.}
1406
1407 \wxheading{Return value}
1408
1409 true if the operation succeeded, false otherwise.
1410
1411 \wxheading{See also}
1412
1413 \helpref{wxImage::LoadFile}{wximageloadfile},
1414 \helpref{wxImage::SaveFile}{wximagesavefile},
1415 \helpref{wxImageHandler::LoadFile}{wximagehandlerloadfile}
1416
1417
1418 \membersection{wxImageHandler::SetName}\label{wximagehandlersetname}
1419
1420 \func{void}{SetName}{\param{const wxString\& }{name}}
1421
1422 Sets the handler name.
1423
1424 \wxheading{Parameters}
1425
1426 \docparam{name}{Handler name.}
1427
1428
1429 \membersection{wxImageHandler::SetExtension}\label{wximagehandlersetextension}
1430
1431 \func{void}{SetExtension}{\param{const wxString\& }{extension}}
1432
1433 Sets the handler extension.
1434
1435 \wxheading{Parameters}
1436
1437 \docparam{extension}{Handler extension.}
1438
1439
1440 \membersection{wxImageHandler::SetMimeType}\label{wximagehandlersetmimetype}
1441
1442 \func{void}{SetMimeType}{\param{const wxString\& }{mimetype}}
1443
1444 Sets the handler MIME type.
1445
1446 \wxheading{Parameters}
1447
1448 \docparam{mimename}{Handler MIME type.}
1449
1450
1451 \membersection{wxImageHandler::SetType}\label{wximagehandlersettype}
1452
1453 \func{void}{SetType}{\param{long }{type}}
1454
1455 Sets the handler type.
1456
1457 \wxheading{Parameters}
1458
1459 \docparam{name}{Handler type.}