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