]> git.saurik.com Git - wxWidgets.git/blame - docs/latex/wx/image.tex
Cured some small doc typos; some WIN16 fixes; transferred DLL WinMain to
[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
4from data, or using the constructor taking a wxBitmap object. An image
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
9A wxImage cannot (currently) be drawn directly to a wxDC. Instead, a platform-specific
12a44087
RR
10wxBitmap object must be created from it, and that bitmap drawn on the wxDC, using
11wxDC::DrawBitmap.
12
1e6d9499
JS
13\wxheading{Derived from}
14
15\helpref{wxObject}{wxobject}
16
17\wxheading{See also}
18
19\helpref{wxBitmap}{wxbitmap}
20
21\latexignore{\rtfignore{\wxheading{Members}}}
22
23\membersection{wxImage::wxImage}\label{wximageconstr}
24
25\func{}{wxImage}{\void}
26
27Default constructor.
28
29\func{}{wxImage}{\param{const wxImage\& }{image}}
30
31Copy constructor.
32
33\func{}{wxImage}{\param{const wxBitmap\&}{ bitmap}}
34
12a44087
RR
35Constructs an image from a platform-dependent bitmap. This preserves
36mask information so that bitmaps and images can be converted back
37and forth without loss in that respect.
1e6d9499
JS
38
39\func{}{wxImage}{\param{int}{ width}, \param{int}{ height}}
40
41Creates an image with the given width and height.
42
f6fcbb63 43\func{}{wxImage}{\param{const wxString\& }{name}, \param{long}{ type = wxBITMAP\_TYPE\_PNG}}
1e6d9499
JS
44
45Loads an image from a file.
46
f6fcbb63 47\func{}{wxImage}{\param{wxInputStream\& }{stream}, \param{long}{ type = wxBITMAP\_TYPE\_PNG}}
45b5751f
JS
48
49Loads an image from an input stream.
50
1e6d9499
JS
51\wxheading{Parameters}
52
53\docparam{width}{Specifies the width of the image.}
54
55\docparam{height}{Specifies the height of the image.}
56
57\docparam{name}{This refers to an image filename. Its meaning is determined by the {\it type} parameter.}
58
45b5751f
JS
59\docparam{stream}{This refers to an input stream. Its meaning is determined by the {\it type} parameter. It is equal to loading from file except that you provide opened stream (file, HTTP or any other custom class).}
60
1e6d9499
JS
61\docparam{type}{May be one of the following:
62
6be663cf 63\twocolwidtha{5cm}%
1e6d9499 64\begin{twocollist}
f6fcbb63
RR
65\twocolitem{{\bf \indexit{wxBITMAP\_TYPE\_BMP}}}{Load a Windows bitmap file.}
66\twocolitem{{\bf \indexit{wxBITMAP\_TYPE\_PNG}}}{Load a PNG bitmap file.}
48b4e302 67\twocolitem{{\bf \indexit{wxBITMAP\_TYPE\_JPEG}}}{Load a JPEG bitmap file.}
1e6d9499
JS
68\end{twocollist}
69
70The validity of these flags depends on the platform and wxWindows configuration.
48b4e302
VS
71If all possible wxWindows settings are used, the loading a BMP (Windows bitmap) file,
72a PNG (portable network graphics) file and a JPEG file is supported on all platforms that
12a44087 73implement wxImage.}
1e6d9499 74
0a9f2522
VS
75Note : you must call wxImage::AddHandler(new wxJPEGHandler) during application
76initialization in order to work with JPEGs.
77
1e6d9499
JS
78\wxheading{See also}
79
80\helpref{wxImage::LoadFile}{wximageloadfile}
81
82\membersection{wxImage::\destruct{wxImage}}
83
84\func{}{\destruct{wxImage}}{\void}
85
86Destructor.
87
88\membersection{wxImage::AddHandler}\label{wximageaddhandler}
89
90\func{static void}{AddHandler}{\param{wxImageHandler*}{ handler}}
91
92Adds a handler to the end of the static list of format handlers.
93
94\docparam{handler}{A new image format handler object. There is usually only one instance
95of a given handler class in an application session.}
96
97\wxheading{See also}
98
99\helpref{wxImageHandler}{wximagehandler}
100
101\membersection{wxImage::CleanUpHandlers}
102
103\func{static void}{CleanUpHandlers}{\void}
104
105Deletes all image handlers.
106
107This function is called by wxWindows on exit.
108
109\membersection{wxImage::ConvertToBitmap}\label{wximageconverttobitmap}
110
111\constfunc{wxBitmap}{ConvertToBitmap}{\void}
112
12a44087
RR
113Converts the image to a platform-specific bitmap object. This has to be done
114to actually display an image as you cannot draw an image directly on a window.
115The resulting bitmap will use the colour depth of the current system which entails
f6fcbb63
RR
116that a (crude) colour reduction has to take place. When in 8-bit mode, this
117routine will use a color cube created on program start-up to look up colors.
118Still, the image quality won't be perfect for photo images.
1e6d9499
JS
119
120\membersection{wxImage::Create}\label{wximagecreate}
121
122\func{bool}{Create}{\param{int}{ width}, \param{int}{ height}}
123
124Creates a fresh image.
125
126\wxheading{Parameters}
127
128\docparam{width}{The width of the image in pixels.}
129
130\docparam{height}{The height of the image in pixels.}
131
132\wxheading{Return value}
133
134TRUE if the call succeeded, FALSE otherwise.
135
136\membersection{wxImage::Destroy}\label{wximagedestroy}
137
138\func{bool}{Destroy}{\void}
139
140Destroys the image data.
141
142\membersection{wxImage::FindHandler}
143
144\func{static wxImageHandler*}{FindHandler}{\param{const wxString\& }{name}}
145
146Finds the handler with the given name.
147
148\func{static wxImageHandler*}{FindHandler}{\param{const wxString\& }{extension}, \param{long}{ imageType}}
149
150Finds the handler associated with the given extension and type.
151
152\func{static wxImageHandler*}{FindHandler}{\param{long }{imageType}}
153
154Finds the handler associated with the given image type.
155
156\docparam{name}{The handler name.}
157
158\docparam{extension}{The file extension, such as ``bmp".}
159
f6fcbb63 160\docparam{imageType}{The image type, such as wxBITMAP\_TYPE\_BMP.}
1e6d9499
JS
161
162\wxheading{Return value}
163
164A pointer to the handler if found, NULL otherwise.
165
166\wxheading{See also}
167
168\helpref{wxImageHandler}{wximagehandler}
169
170\membersection{wxImage::GetBlue}\label{wximagegetblue}
171
172\constfunc{unsigned char}{GetBlue}{\param{int}{ x}, \param{int}{ y}}
173
174Returns the blue intensity at the given coordinate.
175
176\membersection{wxImage::GetData}\label{wximagegetdata}
177
178\constfunc{unsigned char*}{GetData}{\void}
179
12a44087
RR
180Returns the image data as an array. This is most often used when doing
181direct image manipulation. The return value points to an array of
182chararcters in RGBGBRGB... format.
1e6d9499
JS
183
184\membersection{wxImage::GetGreen}\label{wximagegetgreen}
185
186\constfunc{unsigned char}{GetGreen}{\param{int}{ x}, \param{int}{ y}}
187
188Returns the green intensity at the given coordinate.
189
190\membersection{wxImage::GetRed}\label{wximagegetred}
191
192\constfunc{unsigned char}{GetRed}{\param{int}{ x}, \param{int}{ y}}
193
194Returns the red intensity at the given coordinate.
195
196\membersection{wxImage::GetHandlers}
197
198\func{static wxList\&}{GetHandlers}{\void}
199
200Returns the static list of image format handlers.
201
202\wxheading{See also}
203
204\helpref{wxImageHandler}{wximagehandler}
205
206\membersection{wxImage::GetHeight}\label{wximagegetheight}
207
208\constfunc{int}{GetHeight}{\void}
209
210Gets the height of the image in pixels.
211
212\membersection{wxImage::GetMaskBlue}\label{wximagegetmaskblue}
213
214\constfunc{unsigned char}{GetMaskBlue}{\void}
215
216Gets the blue value of the mask colour.
217
218\membersection{wxImage::GetMaskGreen}\label{wximagegetmaskgreen}
219
220\constfunc{unsigned char}{GetMaskGreen}{\void}
221
222Gets the green value of the mask colour.
223
224\membersection{wxImage::GetMaskRed}\label{wximagegetmaskred}
225
226\constfunc{unsigned char}{GetMaskRed}{\void}
227
228Gets the red value of the mask colour.
229
230\membersection{wxImage::GetWidth}\label{wximagegetwidth}
231
232\constfunc{int}{GetWidth}{\void}
233
234Gets the width of the image in pixels.
235
236\wxheading{See also}
237
238\helpref{wxImage::GetHeight}{wximagegetheight}
239
240\membersection{wxImage::HasMask}\label{wximagehasmask}
241
242\constfunc{bool}{HasMask}{\void}
243
244Returns TRUE if there is a mask active, FALSE otherwise.
245
246\membersection{wxImage::InitStandardHandlers}
247
248\func{static void}{InitStandardHandlers}{\void}
249
250Adds the standard image format handlers, which, depending on wxWindows
48b4e302
VS
251configuration, can be handlers for Windows BMP (loading), PNG
252(loading and saving) and JPEG (loading and saving) file formats.
1e6d9499
JS
253
254This function is called by wxWindows on startup.
255
256\wxheading{See also}
257
258\helpref{wxImageHandler}{wximagehandler}
259
260\membersection{wxImage::InsertHandler}
261
262\func{static void}{InsertHandler}{\param{wxImageHandler*}{ handler}}
263
264Adds a handler at the start of the static list of format handlers.
265
266\docparam{handler}{A new image format handler object. There is usually only one instance
267of a given handler class in an application session.}
268
269\wxheading{See also}
270
271\helpref{wxImageHandler}{wximagehandler}
272
273\membersection{wxImage::LoadFile}\label{wximageloadfile}
274
275\func{bool}{LoadFile}{\param{const wxString\&}{ name}, \param{long}{ type}}
276
277Loads an image from a file.
278
45b5751f
JS
279\func{bool}{LoadFile}{\param{wxInputStream\&}{ stream}, \param{long}{ type}}
280
281Loads an image from an input stream.
282
1e6d9499
JS
283\wxheading{Parameters}
284
285\docparam{name}{A filename.
286The meaning of {\it name} is determined by the {\it type} parameter.}
287
45b5751f
JS
288\docparam{stream}{An input stream.
289The meaning of {\it stream} data is determined by the {\it type} parameter.}
290
1e6d9499
JS
291\docparam{type}{One of the following values:
292
6be663cf 293\twocolwidtha{5cm}%
1e6d9499 294\begin{twocollist}
f6fcbb63
RR
295\twocolitem{{\bf wxBITMAP\_TYPE\_BMP}}{Load a Windows image file.}
296\twocolitem{{\bf wxBITMAP\_TYPE\_PNG}}{Load a PNG image file.}
48b4e302 297\twocolitem{{\bf wxBITMAP\_TYPE\_JPEG}}{Load a JPEG image file.}
1e6d9499
JS
298\end{twocollist}
299
300The validity of these flags depends on the platform and wxWindows configuration.}
301
302\wxheading{Return value}
303
304TRUE if the operation succeeded, FALSE otherwise.
305
306\wxheading{See also}
307
308\helpref{wxImage::SaveFile}{wximagesavefile}
309
310\membersection{wxImage::Ok}\label{wximageok}
311
312\constfunc{bool}{Ok}{\void}
313
314Returns TRUE if image data is present.
315
316\membersection{wxImage::RemoveHandler}
317
318\func{static bool}{RemoveHandler}{\param{const wxString\& }{name}}
319
320Finds the handler with the given name, and removes it. The handler
321is not deleted.
322
323\docparam{name}{The handler name.}
324
325\wxheading{Return value}
326
327TRUE if the handler was found and removed, FALSE otherwise.
328
329\wxheading{See also}
330
331\helpref{wxImageHandler}{wximagehandler}
332
333\membersection{wxImage::SaveFile}\label{wximagesavefile}
334
335\func{bool}{SaveFile}{\param{const wxString\& }{name}, \param{int}{ type}}
336
337Saves a image in the named file.
338
45b5751f
JS
339\func{bool}{SaveFile}{\param{wxOutputStream\& }{stream}, \param{int}{ type}}
340
341Saves a image in the given stream.
342
1e6d9499
JS
343\wxheading{Parameters}
344
345\docparam{name}{A filename. The meaning of {\it name} is determined by the {\it type} parameter.}
346
45b5751f
JS
347\docparam{stream}{An output stream. The meaning of {\it stream} is determined by the {\it type} parameter.}
348
48b4e302 349\docparam{type}{Currently two types can be used:
1e6d9499 350
6be663cf 351\twocolwidtha{5cm}%
1e6d9499 352\begin{twocollist}
f6fcbb63 353\twocolitem{{\bf wxBITMAP\_TYPE\_PNG}}{Save a PNG image file.}
48b4e302 354\twocolitem{{\bf wxBITMAP\_TYPE\_JPEG}}{Save a JPEG image file.}
1e6d9499
JS
355\end{twocollist}
356
12a44087
RR
357The validity of these flags depends on the platform and wxWindows configuration
358as well as user-added handlers.}
1e6d9499
JS
359
360\wxheading{Return value}
361
362TRUE if the operation succeeded, FALSE otherwise.
363
364\wxheading{Remarks}
365
366Depending on how wxWindows has been configured, not all formats may be available.
367
368\wxheading{See also}
369
370\helpref{wxImage::LoadFile}{wximageloadfile}
371
372\membersection{wxImage::Scale}\label{wximagescale}
373
374\func{wxImage}{Scale}{\param{int}{ width}, \param{int}{ height}}
375
12a44087
RR
376Returns a scaled version of the image. This is also useful for
377scaling bitmaps in general as the only other way to scale bitmaps
b1170810
RR
378is to blit a wxMemoryDC into another wxMemoryDC. Windows can do such
379scaling itself but in the GTK port, scaling bitmaps is done using
380this routine internally.
1e6d9499
JS
381
382\membersection{wxImage::SetData}\label{wximagesetdata}
383
384\func{void}{SetData}{\param{unsigned char*}{data}}
385
12a44087
RR
386Sets the image data without performing checks. The data given must have
387the size (width*height*3) or results will be unexpected. Don't use this
388method if you aren't sure you know what you are doing.
1e6d9499
JS
389
390\membersection{wxImage::SetMask}\label{wximagesetmask}
391
392\func{void}{SetMask}{\param{bool}{ hasMask = TRUE}}
393
394Specifies whether there is a mask or not. The area of the mask is determined by the current mask colour.
395
396\membersection{wxImage::SetMaskColour}\label{wximagesetmaskcolour}
397
398\func{void}{SetMaskColour}{\param{unsigned char }{red}, \param{unsigned char }{blue}, \param{unsigned char }{green}}
399
b1170810 400Sets the mask colour for this image (and tells the image to use the mask).
1e6d9499
JS
401
402\membersection{wxImage::SetRGB}\label{wximagesetrgb}
403
404\func{void}{SetRGB}{\param{int }{x}, \param{int }{y}, \param{unsigned char }{red}, \param{unsigned char }{blue}, \param{unsigned char }{green}}
405
12a44087
RR
406Sets the pixel at the given coordinate. This routine performs bounds-checks
407for the coordinate so it can be considered a safe way to manipulate the
408data, but in some cases this might be too slow so that the data will have to
409be set directly. In that case you have to get that data by calling GetData().
1e6d9499
JS
410
411\membersection{wxImage::operator $=$}
412
413\func{wxImage\& }{operator $=$}{\param{const wxImage\& }{image}}
414
415Assignment operator. This operator does not copy any data, but instead
416passes a pointer to the data in {\it image} and increments a reference
417counter. It is a fast operation.
418
419\wxheading{Parameters}
420
421\docparam{image}{Image to assign.}
422
423\wxheading{Return value}
424
425Returns 'this' object.
426
427\membersection{wxImage::operator $==$}
428
429\func{bool}{operator $==$}{\param{const wxImage\& }{image}}
430
431Equality operator. This operator tests whether the internal data pointers are
432equal (a fast test).
433
434\wxheading{Parameters}
435
436\docparam{image}{Image to compare with 'this'}
437
438\wxheading{Return value}
439
440Returns TRUE if the images were effectively equal, FALSE otherwise.
441
442\membersection{wxImage::operator $!=$}
443
444\func{bool}{operator $!=$}{\param{const wxImage\& }{image}}
445
446Inequality operator. This operator tests whether the internal data pointers are
447unequal (a fast test).
448
449\wxheading{Parameters}
450
451\docparam{image}{Image to compare with 'this'}
452
453\wxheading{Return value}
454
455Returns TRUE if the images were unequal, FALSE otherwise.
456
457\section{\class{wxImageHandler}}\label{wximagehandler}
458
1e6d9499
JS
459This is the base class for implementing image file loading/saving, and image creation from data.
460It is used within wxImage and is not normally seen by the application.
461
462If you wish to extend the capabilities of wxImage, derive a class from wxImageHandler
463and add the handler using \helpref{wxImage::AddHandler}{wximageaddhandler} in your
464application initialisation.
465
48b4e302
VS
466\wxheading{Note (Legal Issue)}
467
468This software is based in part on the work of
469 the Independent JPEG Group.
470
471(Applies when wxWindows is linked with JPEG support. wxJPEGHandler uses libjpeg
472created by IJG.)
473
1e6d9499
JS
474\wxheading{Derived from}
475
476\helpref{wxObject}{wxobject}
477
478\wxheading{See also}
479
480\helpref{wxImage}{wximage}
481
482\latexignore{\rtfignore{\wxheading{Members}}}
483
484\membersection{wxImageHandler::wxImageHandler}\label{wximagehandlerconstr}
485
486\func{}{wxImageHandler}{\void}
487
488Default constructor. In your own default constructor, initialise the members
489m\_name, m\_extension and m\_type.
490
491\membersection{wxImageHandler::\destruct{wxImageHandler}}
492
493\func{}{\destruct{wxImageHandler}}{\void}
494
495Destroys the wxImageHandler object.
496
497\membersection{wxImageHandler::GetName}
498
499\constfunc{wxString}{GetName}{\void}
500
501Gets the name of this handler.
502
503\membersection{wxImageHandler::GetExtension}
504
505\constfunc{wxString}{GetExtension}{\void}
506
507Gets the file extension associated with this handler.
508
509\membersection{wxImageHandler::GetType}
510
511\constfunc{long}{GetType}{\void}
512
513Gets the image type associated with this handler.
514
515\membersection{wxImageHandler::LoadFile}\label{wximagehandlerloadfile}
516
45b5751f 517\func{bool}{LoadFile}{\param{wxImage* }{image}, \param{wxInputStream\&}{ stream}}
1e6d9499 518
45b5751f 519Loads a image from a stream, putting the resulting data into {\it image}.
1e6d9499
JS
520
521\wxheading{Parameters}
522
523\docparam{image}{The image object which is to be affected by this operation.}
524
45b5751f
JS
525\docparam{stream}{Opened input stream.
526The meaning of {\it stream} is determined by the {\it type} parameter.}
1e6d9499
JS
527
528\wxheading{Return value}
529
530TRUE if the operation succeeded, FALSE otherwise.
531
532\wxheading{See also}
533
534\helpref{wxImage::LoadFile}{wximageloadfile}\\
535\helpref{wxImage::SaveFile}{wximagesavefile}\\
536\helpref{wxImageHandler::SaveFile}{wximagehandlersavefile}
537
538\membersection{wxImageHandler::SaveFile}\label{wximagehandlersavefile}
539
45b5751f 540\func{bool}{SaveFile}{\param{wxImage* }{image}, \param{wxOutputStream\& }{stream}}
1e6d9499 541
45b5751f 542Saves a image in the output stream.
1e6d9499
JS
543
544\wxheading{Parameters}
545
546\docparam{image}{The image object which is to be affected by this operation.}
547
45b5751f 548\docparam{stream}{A stream. The meaning of {\it stream} is determined by the {\it type} parameter.}
1e6d9499
JS
549
550\wxheading{Return value}
551
552TRUE if the operation succeeded, FALSE otherwise.
553
554\wxheading{See also}
555
556\helpref{wxImage::LoadFile}{wximageloadfile}\\
557\helpref{wxImage::SaveFile}{wximagesavefile}\\
558\helpref{wxImageHandler::LoadFile}{wximagehandlerloadfile}
559
560\membersection{wxImageHandler::SetName}
561
562\func{void}{SetName}{\param{const wxString\& }{name}}
563
564Sets the handler name.
565
566\wxheading{Parameters}
567
568\docparam{name}{Handler name.}
569
570\membersection{wxImageHandler::SetExtension}
571
572\func{void}{SetExtension}{\param{const wxString\& }{extension}}
573
574Sets the handler extension.
575
576\wxheading{Parameters}
577
578\docparam{extension}{Handler extension.}
579
580\membersection{wxImageHandler::SetType}
581
582\func{void}{SetType}{\param{long }{type}}
583
584Sets the handler type.
585
586\wxheading{Parameters}
587
588\docparam{name}{Handler type.}
589