]>
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 FM |
534 | |
535 | /** | |
427c415b FM |
536 | @deprecated |
537 | Use the equivalent @ref wxBitmap::wxBitmap "wxBitmap constructor" | |
23324ae1 FM |
538 | (which takes wxImage and depth as its arguments) instead. |
539 | */ | |
328f5751 | 540 | wxBitmap ConvertToBitmap() const; |
23324ae1 FM |
541 | |
542 | /** | |
427c415b FM |
543 | Returns a greyscale version of the image. |
544 | ||
545 | The returned image uses the luminance component of the original to | |
546 | calculate the greyscale. Defaults to using the standard ITU-T BT.601 | |
547 | when converting to YUV, where every pixel equals | |
548 | (R * @a lr) + (G * @a lg) + (B * @a lb). | |
23324ae1 | 549 | */ |
5267aefd | 550 | wxImage ConvertToGreyscale(double lr = 0.299, double lg = 0.587, double lb = 1.114) const; |
23324ae1 FM |
551 | |
552 | /** | |
427c415b FM |
553 | Returns monochromatic version of the image. |
554 | ||
555 | The returned image has white colour where the original has @e (r,g,b) | |
556 | colour and black colour everywhere else. | |
23324ae1 | 557 | */ |
427c415b | 558 | wxImage ConvertToMono(unsigned char r, unsigned char g, unsigned char b) const; |
23324ae1 FM |
559 | |
560 | /** | |
561 | Returns an identical copy of the image. | |
562 | */ | |
328f5751 | 563 | wxImage Copy() const; |
23324ae1 FM |
564 | |
565 | /** | |
ff3050e1 VZ |
566 | Creates a fresh image. |
567 | ||
568 | If @a clear is @true, the new image will be initialized to black. | |
23324ae1 | 569 | Otherwise, the image data will be uninitialized. |
3c4f71cc | 570 | |
7c913512 | 571 | @param width |
4cc4bfaf | 572 | The width of the image in pixels. |
7c913512 | 573 | @param height |
4cc4bfaf | 574 | The height of the image in pixels. |
ff3050e1 VZ |
575 | @param clear |
576 | If @true, initialize the image data with zeros. | |
3c4f71cc | 577 | |
d29a9a8a | 578 | @return @true if the call succeeded, @false otherwise. |
23324ae1 | 579 | */ |
4cc4bfaf | 580 | bool Create(int width, int height, bool clear = true); |
23324ae1 FM |
581 | |
582 | /** | |
583 | Destroys the image data. | |
584 | */ | |
585 | void Destroy(); | |
586 | ||
587 | /** | |
427c415b FM |
588 | Finds the first colour that is never used in the image. |
589 | The search begins at given initial colour and continues by increasing | |
590 | R, G and B components (in this order) by 1 until an unused colour is | |
591 | found or the colour space exhausted. | |
592 | ||
593 | The parameters @a r, @a g, @a b are pointers to variables to save the colour. | |
594 | ||
595 | The parameters @a startR, @a startG, @a startB define the initial values | |
596 | of the colour. | |
597 | The returned colour will have RGB values equal to or greater than these. | |
3c4f71cc | 598 | |
d29a9a8a | 599 | @return Returns @false if there is no unused colour left, @true on success. |
427c415b FM |
600 | |
601 | @note | |
602 | This method involves computing the histogram, which is a | |
603 | computationally intensive operation. | |
23324ae1 | 604 | */ |
4cc4bfaf | 605 | bool FindFirstUnusedColour(unsigned char* r, unsigned char* g, |
adaaa686 | 606 | unsigned char* b, unsigned char startR = 1, |
23324ae1 | 607 | unsigned char startG = 0, |
adaaa686 | 608 | unsigned char startB = 0) const; |
23324ae1 | 609 | |
23324ae1 | 610 | /** |
427c415b | 611 | Finds the handler with the given name. |
3c4f71cc | 612 | |
7c913512 | 613 | @param name |
4cc4bfaf | 614 | The handler name. |
427c415b FM |
615 | |
616 | @return A pointer to the handler if found, @NULL otherwise. | |
617 | ||
618 | @see wxImageHandler | |
619 | */ | |
620 | static wxImageHandler* FindHandler(const wxString& name); | |
621 | ||
622 | /** | |
623 | Finds the handler associated with the given extension and type. | |
624 | ||
7c913512 | 625 | @param extension |
4cc4bfaf | 626 | The file extension, such as "bmp". |
7c913512 | 627 | @param imageType |
427c415b | 628 | The image type; one of the ::wxBitmapType values. |
3c4f71cc | 629 | |
d29a9a8a | 630 | @return A pointer to the handler if found, @NULL otherwise. |
3c4f71cc | 631 | |
4cc4bfaf | 632 | @see wxImageHandler |
23324ae1 | 633 | */ |
7c913512 | 634 | static wxImageHandler* FindHandler(const wxString& extension, |
e98e625c | 635 | wxBitmapType imageType); |
427c415b FM |
636 | |
637 | /** | |
638 | Finds the handler associated with the given image type. | |
639 | ||
640 | @param imageType | |
641 | The image type; one of the ::wxBitmapType values. | |
642 | ||
643 | @return A pointer to the handler if found, @NULL otherwise. | |
644 | ||
645 | @see wxImageHandler | |
646 | */ | |
e98e625c | 647 | static wxImageHandler* FindHandler(wxBitmapType imageType); |
427c415b FM |
648 | |
649 | /** | |
650 | Finds the handler associated with the given MIME type. | |
651 | ||
652 | @param mimetype | |
653 | MIME type. | |
654 | ||
655 | @return A pointer to the handler if found, @NULL otherwise. | |
656 | ||
657 | @see wxImageHandler | |
658 | */ | |
7c913512 | 659 | static wxImageHandler* FindHandlerMime(const wxString& mimetype); |
23324ae1 | 660 | |
b3623ed5 RR |
661 | /** |
662 | Return alpha value at given pixel location. | |
663 | */ | |
664 | unsigned char GetAlpha(int x, int y) const; | |
e98e625c | 665 | |
23324ae1 | 666 | /** |
427c415b FM |
667 | Returns pointer to the array storing the alpha values for this image. |
668 | ||
669 | This pointer is @NULL for the images without the alpha channel. If the image | |
23324ae1 | 670 | does have it, this pointer may be used to directly manipulate the alpha values |
b3623ed5 | 671 | which are stored as the RGB ones. |
23324ae1 | 672 | */ |
0a98423e | 673 | unsigned char* GetAlpha() const; |
23324ae1 FM |
674 | |
675 | /** | |
676 | Returns the blue intensity at the given coordinate. | |
677 | */ | |
328f5751 | 678 | unsigned char GetBlue(int x, int y) const; |
23324ae1 FM |
679 | |
680 | /** | |
427c415b FM |
681 | Returns the image data as an array. |
682 | ||
683 | This is most often used when doing direct image manipulation. | |
684 | The return value points to an array of characters in RGBRGBRGB... format | |
685 | in the top-to-bottom, left-to-right order, that is the first RGB triplet | |
686 | corresponds to the pixel first pixel of the first row, the second one --- | |
687 | to the second pixel of the first row and so on until the end of the first | |
688 | row, with second row following after it and so on. | |
689 | ||
690 | You should not delete the returned pointer nor pass it to SetData(). | |
23324ae1 | 691 | */ |
328f5751 | 692 | unsigned char* GetData() const; |
23324ae1 FM |
693 | |
694 | /** | |
695 | Returns the green intensity at the given coordinate. | |
696 | */ | |
328f5751 | 697 | unsigned char GetGreen(int x, int y) const; |
23324ae1 FM |
698 | |
699 | /** | |
700 | Returns the static list of image format handlers. | |
3c4f71cc | 701 | |
4cc4bfaf | 702 | @see wxImageHandler |
23324ae1 FM |
703 | */ |
704 | static wxList GetHandlers(); | |
705 | ||
706 | /** | |
707 | Gets the height of the image in pixels. | |
c74b07ac FM |
708 | |
709 | @see GetWidth(), GetSize() | |
23324ae1 | 710 | */ |
328f5751 | 711 | int GetHeight() const; |
23324ae1 FM |
712 | |
713 | //@{ | |
714 | /** | |
427c415b FM |
715 | If the image file contains more than one image and the image handler is |
716 | capable of retrieving these individually, this function will return the | |
717 | number of available images. | |
718 | ||
719 | For the overload taking the parameter @a filename, that's the name | |
720 | of the file to query. | |
721 | For the overload taking the parameter @a stream, that's the ppened input | |
722 | stream with image data. Currently, the stream must support seeking. | |
723 | ||
724 | The parameter @a type may be one of the following values: | |
725 | @li wxBITMAP_TYPE_BMP: Load a Windows bitmap file. | |
726 | @li wxBITMAP_TYPE_GIF: Load a GIF bitmap file. | |
727 | @li wxBITMAP_TYPE_JPEG: Load a JPEG bitmap file. | |
728 | @li wxBITMAP_TYPE_PNG: Load a PNG bitmap file. | |
729 | @li wxBITMAP_TYPE_PCX: Load a PCX bitmap file. | |
730 | @li wxBITMAP_TYPE_PNM: Load a PNM bitmap file. | |
731 | @li wxBITMAP_TYPE_TIF: Load a TIFF bitmap file. | |
732 | @li wxBITMAP_TYPE_TGA: Load a TGA bitmap file. | |
733 | @li wxBITMAP_TYPE_XPM: Load a XPM bitmap file. | |
734 | @li wxBITMAP_TYPE_ICO: Load a Windows icon file (ICO). | |
735 | @li wxBITMAP_TYPE_CUR: Load a Windows cursor file (CUR). | |
736 | @li wxBITMAP_TYPE_ANI: Load a Windows animated cursor file (ANI). | |
737 | @li wxBITMAP_TYPE_ANY: Will try to autodetect the format. | |
3c4f71cc | 738 | |
d29a9a8a | 739 | @return Number of available images. For most image handlers, this is 1 |
427c415b | 740 | (exceptions are TIFF and ICO formats). |
23324ae1 FM |
741 | */ |
742 | static int GetImageCount(const wxString& filename, | |
e98e625c | 743 | wxBitmapType type = wxBITMAP_TYPE_ANY); |
7c913512 | 744 | static int GetImageCount(wxInputStream& stream, |
e98e625c | 745 | wxBitmapType type = wxBITMAP_TYPE_ANY); |
23324ae1 FM |
746 | //@} |
747 | ||
748 | /** | |
749 | Iterates all registered wxImageHandler objects, and returns a string containing | |
427c415b FM |
750 | file extension masks suitable for passing to file open/save dialog boxes. |
751 | ||
752 | @return The format of the returned string is @c "(*.ext1;*.ext2)|*.ext1;*.ext2". | |
753 | It is usually a good idea to prepend a description before passing | |
754 | the result to the dialog. | |
755 | Example: | |
756 | @code | |
757 | wxFileDialog FileDlg( this, "Choose Image", ::wxGetCwd(), "", | |
758 | _("Image Files ") + wxImage::GetImageExtWildcard(), | |
759 | wxFD_OPEN ); | |
760 | @endcode | |
3c4f71cc | 761 | |
4cc4bfaf | 762 | @see wxImageHandler |
23324ae1 FM |
763 | */ |
764 | static wxString GetImageExtWildcard(); | |
765 | ||
766 | /** | |
767 | Gets the blue value of the mask colour. | |
768 | */ | |
328f5751 | 769 | unsigned char GetMaskBlue() const; |
23324ae1 FM |
770 | |
771 | /** | |
772 | Gets the green value of the mask colour. | |
773 | */ | |
328f5751 | 774 | unsigned char GetMaskGreen() const; |
23324ae1 FM |
775 | |
776 | /** | |
777 | Gets the red value of the mask colour. | |
778 | */ | |
328f5751 | 779 | unsigned char GetMaskRed() const; |
23324ae1 FM |
780 | |
781 | /** | |
09b898e0 | 782 | Gets a user-defined string-valued option. |
427c415b | 783 | |
09b898e0 VZ |
784 | Currently the only defined string option is |
785 | @li wxIMAGE_OPTION_FILENAME: The name of the file from which the image | |
786 | was loaded. | |
3c4f71cc | 787 | |
4cc4bfaf | 788 | @see SetOption(), GetOptionInt(), HasOption() |
09b898e0 VZ |
789 | |
790 | @param name | |
791 | The name of the option, case-insensitive. | |
792 | @return | |
793 | The value of the option or an empty string if not found. Use | |
794 | HasOption() if an empty string can be a valid option value. | |
23324ae1 | 795 | */ |
328f5751 | 796 | wxString GetOption(const wxString& name) const; |
23324ae1 FM |
797 | |
798 | /** | |
09b898e0 VZ |
799 | Gets a user-defined integer-valued option. |
800 | ||
427c415b FM |
801 | The function is case-insensitive to @a name. |
802 | If the given option is not present, the function returns 0. | |
4e2cddc4 | 803 | Use HasOption() is 0 is a possibly valid value for the option. |
427c415b | 804 | |
09b898e0 | 805 | Generic options: |
36abe9d4 VZ |
806 | @li wxIMAGE_OPTION_MAX_WIDTH and wxIMAGE_OPTION_MAX_HEIGHT: If either |
807 | of these options is specified, the loaded image will be scaled down | |
808 | (preserving its aspect ratio) so that its width is less than the | |
809 | max width given if it is not 0 @em and its height is less than the | |
810 | max height given if it is not 0. This is typically used for loading | |
811 | thumbnails and the advantage of using these options compared to | |
812 | calling Rescale() after loading is that some handlers (only JPEG | |
813 | one right now) support rescaling the image during loading which is | |
814 | vastly more efficient than loading the entire huge image and | |
815 | rescaling it later (if these options are not supported by the | |
816 | handler, this is still what happens however). These options must be | |
817 | set before calling LoadFile() to have any effect. | |
818 | ||
09b898e0 VZ |
819 | @li wxIMAGE_OPTION_QUALITY: JPEG quality used when saving. This is an |
820 | integer in 0..100 range with 0 meaning very poor and 100 excellent | |
821 | (but very badly compressed). This option is currently ignored for | |
822 | the other formats. | |
823 | ||
824 | @li wxIMAGE_OPTION_RESOLUTIONUNIT: The value of this option determines | |
825 | whether the resolution of the image is specified in centimetres or | |
826 | inches, see wxImageResolution enum elements. | |
827 | ||
828 | @li wxIMAGE_OPTION_RESOLUTION, wxIMAGE_OPTION_RESOLUTIONX and | |
829 | wxIMAGE_OPTION_RESOLUTIONY: These options define the resolution of | |
830 | the image in the units corresponding to wxIMAGE_OPTION_RESOLUTIONUNIT | |
831 | options value. The first option can be set before saving the image | |
832 | to set both horizontal and vertical resolution to the same value. | |
833 | The X and Y options are set by the image handlers if they support | |
834 | the image resolution (currently BMP, JPEG and TIFF handlers do) and | |
835 | the image provides the resolution information and can be queried | |
836 | after loading the image. | |
837 | ||
838 | Options specific to wxPNGHandler: | |
839 | @li wxIMAGE_OPTION_PNG_FORMAT: Format for saving a PNG file, see | |
840 | wxImagePNGType for the supported values. | |
4e2cddc4 | 841 | @li wxIMAGE_OPTION_PNG_BITDEPTH: Bit depth for every channel (R/G/B/A). |
e98e625c | 842 | |
4cc4bfaf | 843 | @see SetOption(), GetOption() |
09b898e0 VZ |
844 | |
845 | @param name | |
846 | The name of the option, case-insensitive. | |
847 | @return | |
848 | The value of the option or 0 if not found. Use HasOption() if 0 | |
849 | can be a valid option value. | |
23324ae1 | 850 | */ |
328f5751 | 851 | int GetOptionInt(const wxString& name) const; |
23324ae1 FM |
852 | |
853 | /** | |
854 | Get the current mask colour or find a suitable unused colour that could be | |
855 | used as a mask colour. Returns @true if the image currently has a mask. | |
856 | */ | |
5267aefd FM |
857 | bool GetOrFindMaskColour(unsigned char* r, unsigned char* g, |
858 | unsigned char* b) const; | |
23324ae1 FM |
859 | |
860 | /** | |
427c415b FM |
861 | Returns the palette associated with the image. |
862 | Currently the palette is only used when converting to wxBitmap under Windows. | |
863 | ||
864 | Some of the wxImage handlers have been modified to set the palette if | |
865 | one exists in the image file (usually 256 or less colour images in | |
866 | GIF or PNG format). | |
23324ae1 | 867 | */ |
427c415b | 868 | const wxPalette& GetPalette() const; |
23324ae1 FM |
869 | |
870 | /** | |
871 | Returns the red intensity at the given coordinate. | |
872 | */ | |
328f5751 | 873 | unsigned char GetRed(int x, int y) const; |
23324ae1 FM |
874 | |
875 | /** | |
427c415b FM |
876 | Returns a sub image of the current one as long as the rect belongs entirely |
877 | to the image. | |
23324ae1 | 878 | */ |
328f5751 | 879 | wxImage GetSubImage(const wxRect& rect) const; |
23324ae1 | 880 | |
c74b07ac FM |
881 | /** |
882 | Returns the size of the image in pixels. | |
883 | ||
884 | @since 2.9.0 | |
885 | ||
886 | @see GetHeight(), GetWidth() | |
887 | */ | |
888 | wxSize GetSize() const; | |
889 | ||
591d3fa2 | 890 | /** |
427c415b FM |
891 | Gets the type of image found by LoadFile() or specified with SaveFile(). |
892 | ||
591d3fa2 VZ |
893 | @since 2.9.0 |
894 | */ | |
895 | wxBitmapType GetType() const; | |
896 | ||
23324ae1 FM |
897 | /** |
898 | Gets the width of the image in pixels. | |
3c4f71cc | 899 | |
c74b07ac | 900 | @see GetHeight(), GetSize() |
23324ae1 | 901 | */ |
328f5751 | 902 | int GetWidth() const; |
23324ae1 | 903 | |
23324ae1 FM |
904 | /** |
905 | Converts a color in HSV color space to RGB color space. | |
906 | */ | |
5267aefd | 907 | static wxImage::RGBValue HSVtoRGB(const wxImage::HSVValue& hsv); |
23324ae1 FM |
908 | |
909 | /** | |
910 | Returns @true if this image has alpha channel, @false otherwise. | |
3c4f71cc | 911 | |
4cc4bfaf | 912 | @see GetAlpha(), SetAlpha() |
23324ae1 | 913 | */ |
328f5751 | 914 | bool HasAlpha() const; |
23324ae1 FM |
915 | |
916 | /** | |
917 | Returns @true if there is a mask active, @false otherwise. | |
918 | */ | |
328f5751 | 919 | bool HasMask() const; |
23324ae1 FM |
920 | |
921 | /** | |
427c415b FM |
922 | Returns @true if the given option is present. |
923 | The function is case-insensitive to @a name. | |
3c4f71cc | 924 | |
4cc4bfaf | 925 | @see SetOption(), GetOption(), GetOptionInt() |
23324ae1 | 926 | */ |
328f5751 | 927 | bool HasOption(const wxString& name) const; |
23324ae1 FM |
928 | |
929 | /** | |
427c415b FM |
930 | Initializes the image alpha channel data. |
931 | ||
932 | It is an error to call it if the image already has alpha data. | |
933 | If it doesn't, alpha data will be by default initialized to all pixels | |
934 | being fully opaque. But if the image has a mask colour, all mask pixels | |
935 | will be completely transparent. | |
23324ae1 FM |
936 | */ |
937 | void InitAlpha(); | |
938 | ||
939 | /** | |
427c415b FM |
940 | Internal use only. Adds standard image format handlers. |
941 | It only install wxBMPHandler for the time being, which is used by wxBitmap. | |
942 | ||
23324ae1 FM |
943 | This function is called by wxWidgets on startup, and shouldn't be called by |
944 | the user. | |
3c4f71cc | 945 | |
e54c96f1 | 946 | @see wxImageHandler, wxInitAllImageHandlers(), wxQuantize |
23324ae1 FM |
947 | */ |
948 | static void InitStandardHandlers(); | |
949 | ||
950 | /** | |
951 | Adds a handler at the start of the static list of format handlers. | |
3c4f71cc | 952 | |
7c913512 | 953 | @param handler |
4cc4bfaf FM |
954 | A new image format handler object. There is usually only one instance |
955 | of a given handler class in an application session. | |
3c4f71cc | 956 | |
4cc4bfaf | 957 | @see wxImageHandler |
23324ae1 FM |
958 | */ |
959 | static void InsertHandler(wxImageHandler* handler); | |
960 | ||
961 | /** | |
962 | Returns @true if image data is present. | |
963 | */ | |
328f5751 | 964 | bool IsOk() const; |
23324ae1 FM |
965 | |
966 | /** | |
967 | Returns @true if the given pixel is transparent, i.e. either has the mask | |
968 | colour if this image has a mask or if this image has alpha channel and alpha | |
427c415b | 969 | value of this pixel is strictly less than @a threshold. |
23324ae1 | 970 | */ |
5267aefd FM |
971 | bool IsTransparent(int x, int y, |
972 | unsigned char threshold = wxIMAGE_ALPHA_THRESHOLD) const; | |
23324ae1 | 973 | |
23324ae1 FM |
974 | /** |
975 | Loads an image from an input stream. | |
3c4f71cc | 976 | |
7c913512 | 977 | @param stream |
427c415b FM |
978 | Opened input stream from which to load the image. |
979 | Currently, the stream must support seeking. | |
7c913512 | 980 | @param type |
dd067e96 | 981 | May be one of the following: |
4e2cddc4 RR |
982 | @li wxBITMAP_TYPE_BMP: Load a Windows bitmap file. |
983 | @li wxBITMAP_TYPE_GIF: Load a GIF bitmap file. | |
984 | @li wxBITMAP_TYPE_JPEG: Load a JPEG bitmap file. | |
985 | @li wxBITMAP_TYPE_PNG: Load a PNG bitmap file. | |
986 | @li wxBITMAP_TYPE_PCX: Load a PCX bitmap file. | |
987 | @li wxBITMAP_TYPE_PNM: Load a PNM bitmap file. | |
988 | @li wxBITMAP_TYPE_TIF: Load a TIFF bitmap file. | |
989 | @li wxBITMAP_TYPE_TGA: Load a TGA bitmap file. | |
990 | @li wxBITMAP_TYPE_XPM: Load a XPM bitmap file. | |
991 | @li wxBITMAP_TYPE_ICO: Load a Windows icon file (ICO). | |
992 | @li wxBITMAP_TYPE_CUR: Load a Windows cursor file (CUR). | |
993 | @li wxBITMAP_TYPE_ANI: Load a Windows animated cursor file (ANI). | |
994 | @li wxBITMAP_TYPE_ANY: Will try to autodetect the format. | |
7c913512 | 995 | @param index |
4cc4bfaf | 996 | Index of the image to load in the case that the image file contains |
dd067e96 RR |
997 | multiple images. This is only used by GIF, ICO and TIFF handlers. |
998 | The default value (-1) means "choose the default image" and is | |
999 | interpreted as the first image (index=0) by the GIF and TIFF handler | |
1000 | and as the largest and most colourful one by the ICO handler. | |
3c4f71cc | 1001 | |
427c415b FM |
1002 | @return @true if the operation succeeded, @false otherwise. |
1003 | If the optional index parameter is out of range, @false is | |
1004 | returned and a call to wxLogError() takes place. | |
3c4f71cc | 1005 | |
23324ae1 | 1006 | @remarks Depending on how wxWidgets has been configured, not all formats |
4cc4bfaf | 1007 | may be available. |
3c4f71cc | 1008 | |
427c415b FM |
1009 | @note |
1010 | You can use GetOptionInt() to get the hotspot when loading cursor files: | |
1011 | @code | |
1012 | int hotspot_x = image.GetOptionInt(wxIMAGE_OPTION_CUR_HOTSPOT_X); | |
1013 | int hotspot_y = image.GetOptionInt(wxIMAGE_OPTION_CUR_HOTSPOT_Y); | |
1014 | @endcode | |
1015 | ||
4cc4bfaf | 1016 | @see SaveFile() |
23324ae1 | 1017 | */ |
0a98423e FM |
1018 | virtual bool LoadFile(wxInputStream& stream, |
1019 | wxBitmapType type = wxBITMAP_TYPE_ANY, | |
1020 | int index = -1); | |
427c415b FM |
1021 | |
1022 | /** | |
1023 | Loads an image from a file. | |
1024 | If no handler type is provided, the library will try to autodetect the format. | |
1025 | ||
1026 | @param name | |
1027 | Name of the file from which to load the image. | |
1028 | @param type | |
1029 | See the description in the LoadFile(wxInputStream&, wxBitmapType, int) overload. | |
1030 | @param index | |
1031 | See the description in the LoadFile(wxInputStream&, wxBitmapType, int) overload. | |
1032 | */ | |
7323ff1a FM |
1033 | virtual bool LoadFile(const wxString& name, |
1034 | wxBitmapType type = wxBITMAP_TYPE_ANY, | |
1035 | int index = -1); | |
427c415b FM |
1036 | |
1037 | /** | |
1038 | Loads an image from a file. | |
1039 | If no handler type is provided, the library will try to autodetect the format. | |
1040 | ||
1041 | @param name | |
1042 | Name of the file from which to load the image. | |
1043 | @param mimetype | |
1044 | MIME type string (for example 'image/jpeg') | |
1045 | @param index | |
1046 | See the description in the LoadFile(wxInputStream&, wxBitmapType, int) overload. | |
1047 | */ | |
fadc2df6 FM |
1048 | virtual bool LoadFile(const wxString& name, const wxString& mimetype, |
1049 | int index = -1); | |
427c415b FM |
1050 | |
1051 | ||
1052 | /** | |
1053 | Loads an image from an input stream. | |
1054 | ||
1055 | @param stream | |
1056 | Opened input stream from which to load the image. | |
1057 | Currently, the stream must support seeking. | |
1058 | @param mimetype | |
1059 | MIME type string (for example 'image/jpeg') | |
1060 | @param index | |
1061 | See the description in the LoadFile(wxInputStream&, wxBitmapType, int) overload. | |
1062 | */ | |
7323ff1a FM |
1063 | virtual bool LoadFile(wxInputStream& stream, const wxString& mimetype, |
1064 | int index = -1); | |
23324ae1 FM |
1065 | |
1066 | /** | |
427c415b FM |
1067 | Returns a mirrored copy of the image. |
1068 | The parameter @a horizontally indicates the orientation. | |
23324ae1 | 1069 | */ |
328f5751 | 1070 | wxImage Mirror(bool horizontally = true) const; |
23324ae1 FM |
1071 | |
1072 | /** | |
4cc4bfaf | 1073 | Copy the data of the given @a image to the specified position in this image. |
23324ae1 FM |
1074 | */ |
1075 | void Paste(const wxImage& image, int x, int y); | |
1076 | ||
23324ae1 FM |
1077 | /** |
1078 | Converts a color in RGB color space to HSV color space. | |
1079 | */ | |
5267aefd | 1080 | static wxImage::HSVValue RGBtoHSV(const wxImage::RGBValue& rgb); |
23324ae1 FM |
1081 | |
1082 | /** | |
427c415b FM |
1083 | Finds the handler with the given name, and removes it. |
1084 | The handler is not deleted. | |
3c4f71cc | 1085 | |
7c913512 | 1086 | @param name |
4cc4bfaf | 1087 | The handler name. |
3c4f71cc | 1088 | |
d29a9a8a | 1089 | @return @true if the handler was found and removed, @false otherwise. |
3c4f71cc | 1090 | |
4cc4bfaf | 1091 | @see wxImageHandler |
23324ae1 FM |
1092 | */ |
1093 | static bool RemoveHandler(const wxString& name); | |
1094 | ||
1095 | /** | |
1096 | Replaces the colour specified by @e r1,g1,b1 by the colour @e r2,g2,b2. | |
1097 | */ | |
1098 | void Replace(unsigned char r1, unsigned char g1, | |
1099 | unsigned char b1, unsigned char r2, | |
1100 | unsigned char g2, unsigned char b2); | |
1101 | ||
1102 | /** | |
1103 | Changes the size of the image in-place by scaling it: after a call to this | |
427c415b FM |
1104 | function,the image will have the given width and height. |
1105 | ||
4cc4bfaf | 1106 | For a description of the @a quality parameter, see the Scale() function. |
23324ae1 | 1107 | Returns the (modified) image itself. |
3c4f71cc | 1108 | |
4cc4bfaf | 1109 | @see Scale() |
23324ae1 | 1110 | */ |
5267aefd | 1111 | wxImage& Rescale(int width, int height, |
23324ae1 FM |
1112 | int quality = wxIMAGE_QUALITY_NORMAL); |
1113 | ||
1114 | /** | |
1115 | Changes the size of the image in-place without scaling it by adding either a | |
427c415b FM |
1116 | border with the given colour or cropping as necessary. |
1117 | ||
1118 | The image is pasted into a new image with the given @a size and background | |
1119 | colour at the position @a pos relative to the upper left of the new image. | |
1120 | ||
1121 | If @a red = green = blue = -1 then use either the current mask colour | |
1122 | if set or find, use, and set a suitable mask colour for any newly exposed | |
1123 | areas. | |
1124 | ||
1125 | @return The (modified) image itself. | |
3c4f71cc | 1126 | |
4cc4bfaf | 1127 | @see Size() |
23324ae1 | 1128 | */ |
5267aefd FM |
1129 | wxImage& Resize(const wxSize& size, const wxPoint& pos, int red = -1, |
1130 | int green = -1, int blue = -1); | |
23324ae1 FM |
1131 | |
1132 | /** | |
427c415b FM |
1133 | Rotates the image about the given point, by @a angle radians. |
1134 | ||
1135 | Passing @true to @a interpolating results in better image quality, but is slower. | |
1136 | ||
1137 | If the image has a mask, then the mask colour is used for the uncovered | |
1138 | pixels in the rotated image background. Else, black (rgb 0, 0, 0) will be used. | |
1139 | ||
23324ae1 FM |
1140 | Returns the rotated image, leaving this image intact. |
1141 | */ | |
1142 | wxImage Rotate(double angle, const wxPoint& rotationCentre, | |
4cc4bfaf | 1143 | bool interpolating = true, |
adaaa686 | 1144 | wxPoint* offsetAfterRotation = NULL) const; |
23324ae1 FM |
1145 | |
1146 | /** | |
1147 | Returns a copy of the image rotated 90 degrees in the direction | |
427c415b | 1148 | indicated by @a clockwise. |
23324ae1 | 1149 | */ |
328f5751 | 1150 | wxImage Rotate90(bool clockwise = true) const; |
23324ae1 FM |
1151 | |
1152 | /** | |
1153 | Rotates the hue of each pixel in the image by @e angle, which is a double in | |
1154 | the range of -1.0 to +1.0, where -1.0 corresponds to -360 degrees and +1.0 | |
427c415b | 1155 | corresponds to +360 degrees. |
23324ae1 FM |
1156 | */ |
1157 | void RotateHue(double angle); | |
1158 | ||
23324ae1 FM |
1159 | /** |
1160 | Saves an image in the given stream. | |
3c4f71cc | 1161 | |
7c913512 | 1162 | @param stream |
4cc4bfaf | 1163 | Opened output stream to save the image to. |
427c415b FM |
1164 | @param mimetype |
1165 | MIME type. | |
1166 | ||
1167 | @return @true if the operation succeeded, @false otherwise. | |
1168 | ||
1169 | @remarks Depending on how wxWidgets has been configured, not all formats | |
1170 | may be available. | |
1171 | ||
1172 | @note | |
1173 | You can use SetOption() to set the hotspot when saving an image | |
1174 | into a cursor file (default hotspot is in the centre of the image): | |
1175 | @code | |
1176 | image.SetOption(wxIMAGE_OPTION_CUR_HOTSPOT_X, hotspotX); | |
1177 | image.SetOption(wxIMAGE_OPTION_CUR_HOTSPOT_Y, hotspotY); | |
1178 | @endcode | |
1179 | ||
1180 | @see LoadFile() | |
1181 | */ | |
fadc2df6 FM |
1182 | virtual bool SaveFile(wxOutputStream& stream, |
1183 | const wxString& mimetype) const; | |
427c415b FM |
1184 | |
1185 | /** | |
1186 | Saves an image in the named file. | |
1187 | ||
1188 | @param name | |
1189 | Name of the file to save the image to. | |
7c913512 | 1190 | @param type |
4cc4bfaf | 1191 | Currently these types can be used: |
4e2cddc4 RR |
1192 | @li wxBITMAP_TYPE_BMP: Save a BMP image file. |
1193 | @li wxBITMAP_TYPE_JPEG: Save a JPEG image file. | |
1194 | @li wxBITMAP_TYPE_PNG: Save a PNG image file. | |
427c415b FM |
1195 | @li wxBITMAP_TYPE_PCX: Save a PCX image file |
1196 | (tries to save as 8-bit if possible, falls back to 24-bit otherwise). | |
4e2cddc4 RR |
1197 | @li wxBITMAP_TYPE_PNM: Save a PNM image file (as raw RGB always). |
1198 | @li wxBITMAP_TYPE_TIFF: Save a TIFF image file. | |
1199 | @li wxBITMAP_TYPE_XPM: Save a XPM image file. | |
427c415b FM |
1200 | @li wxBITMAP_TYPE_ICO: Save a Windows icon file (ICO). |
1201 | The size may be up to 255 wide by 127 high. A single image is saved | |
1202 | in 8 colors at the size supplied. | |
4e2cddc4 | 1203 | @li wxBITMAP_TYPE_CUR: Save a Windows cursor file (CUR). |
427c415b | 1204 | */ |
7323ff1a | 1205 | virtual bool SaveFile(const wxString& name, wxBitmapType type) const; |
427c415b FM |
1206 | |
1207 | /** | |
1208 | Saves an image in the named file. | |
1209 | ||
1210 | @param name | |
1211 | Name of the file to save the image to. | |
7c913512 | 1212 | @param mimetype |
4cc4bfaf | 1213 | MIME type. |
427c415b | 1214 | */ |
fadc2df6 | 1215 | virtual bool SaveFile(const wxString& name, const wxString& mimetype) const; |
3c4f71cc | 1216 | |
427c415b FM |
1217 | /** |
1218 | Saves an image in the named file. | |
3c4f71cc | 1219 | |
427c415b FM |
1220 | File type is determined from the extension of the file name. |
1221 | Note that this function may fail if the extension is not recognized! | |
1222 | You can use one of the forms above to save images to files with | |
1223 | non-standard extensions. | |
3c4f71cc | 1224 | |
427c415b FM |
1225 | @param name |
1226 | Name of the file to save the image to. | |
23324ae1 | 1227 | */ |
7323ff1a | 1228 | virtual bool SaveFile(const wxString& name) const; |
427c415b FM |
1229 | |
1230 | /** | |
1231 | Saves an image in the given stream. | |
1232 | ||
1233 | @param stream | |
1234 | Opened output stream to save the image to. | |
1235 | @param type | |
1236 | MIME type. | |
1237 | */ | |
7323ff1a | 1238 | virtual bool SaveFile(wxOutputStream& stream, wxBitmapType type) const; |
23324ae1 FM |
1239 | |
1240 | /** | |
427c415b FM |
1241 | Returns a scaled version of the image. |
1242 | ||
1243 | This is also useful for scaling bitmaps in general as the only other way | |
1244 | to scale bitmaps is to blit a wxMemoryDC into another wxMemoryDC. | |
1245 | ||
1246 | The parameter @a quality determines what method to use for resampling the image. | |
1247 | Can be one of the following: | |
1248 | - wxIMAGE_QUALITY_NORMAL: Uses the normal default scaling method of pixel | |
1249 | replication | |
1250 | - wxIMAGE_QUALITY_HIGH: Uses bicubic and box averaging resampling methods | |
1251 | for upsampling and downsampling respectively | |
1252 | ||
1253 | It should be noted that although using @c wxIMAGE_QUALITY_HIGH produces much nicer | |
1254 | looking results it is a slower method. Downsampling will use the box averaging | |
1255 | method which seems to operate very fast. If you are upsampling larger images using | |
23324ae1 | 1256 | this method you will most likely notice that it is a bit slower and in extreme |
427c415b FM |
1257 | cases it will be quite substantially slower as the bicubic algorithm has to process a |
1258 | lot of data. | |
1259 | ||
23324ae1 FM |
1260 | It should also be noted that the high quality scaling may not work as expected |
1261 | when using a single mask colour for transparency, as the scaling will blur the | |
1262 | image and will therefore remove the mask partially. Using the alpha channel | |
1263 | will work. | |
e98e625c | 1264 | |
427c415b FM |
1265 | Example: |
1266 | @code | |
1267 | // get the bitmap from somewhere | |
1268 | wxBitmap bmp = ...; | |
1269 | ||
1270 | // rescale it to have size of 32*32 | |
1271 | if ( bmp.GetWidth() != 32 || bmp.GetHeight() != 32 ) | |
1272 | { | |
1273 | wxImage image = bmp.ConvertToImage(); | |
1274 | bmp = wxBitmap(image.Scale(32, 32)); | |
1275 | ||
1276 | // another possibility: | |
1277 | image.Rescale(32, 32); | |
1278 | bmp = image; | |
1279 | } | |
1280 | @endcode | |
3c4f71cc | 1281 | |
4cc4bfaf | 1282 | @see Rescale() |
23324ae1 FM |
1283 | */ |
1284 | wxImage Scale(int width, int height, | |
328f5751 | 1285 | int quality = wxIMAGE_QUALITY_NORMAL) const; |
23324ae1 | 1286 | |
e98e625c | 1287 | /** |
427c415b FM |
1288 | This function is similar to SetData() and has similar restrictions. |
1289 | ||
1290 | The pointer passed to it may however be @NULL in which case the function | |
1291 | will allocate the alpha array internally -- this is useful to add alpha | |
1292 | channel data to an image which doesn't have any. | |
1293 | ||
1294 | If the pointer is not @NULL, it must have one byte for each image pixel | |
1295 | and be allocated with malloc(). | |
1296 | wxImage takes ownership of the pointer and will free it unless @a static_data | |
1297 | parameter is set to @true -- in this case the caller should do it. | |
23324ae1 | 1298 | */ |
4cc4bfaf FM |
1299 | void SetAlpha(unsigned char* alpha = NULL, |
1300 | bool static_data = false); | |
e98e625c | 1301 | |
b3623ed5 | 1302 | /** |
427c415b FM |
1303 | Sets the alpha value for the given pixel. |
1304 | This function should only be called if the image has alpha channel data, | |
1305 | use HasAlpha() to check for this. | |
b3623ed5 | 1306 | */ |
7c913512 | 1307 | void SetAlpha(int x, int y, unsigned char alpha); |
23324ae1 | 1308 | |
0a98423e | 1309 | //@{ |
23324ae1 | 1310 | /** |
427c415b FM |
1311 | Sets the image data without performing checks. |
1312 | ||
1313 | The data given must have the size (width*height*3) or results will be | |
1314 | unexpected. Don't use this method if you aren't sure you know what you | |
1315 | are doing. | |
1316 | ||
23324ae1 FM |
1317 | The data must have been allocated with @c malloc(), @b NOT with |
1318 | @c operator new. | |
427c415b | 1319 | |
23324ae1 FM |
1320 | After this call the pointer to the data is owned by the wxImage object, |
1321 | that will be responsible for deleting it. | |
427c415b | 1322 | Do not pass to this function a pointer obtained through GetData(). |
23324ae1 | 1323 | */ |
0a98423e FM |
1324 | void SetData(unsigned char* data, bool static_data = false); |
1325 | void SetData(unsigned char* data, int new_width, int new_height, | |
1326 | bool static_data = false); | |
1327 | //@} | |
23324ae1 FM |
1328 | |
1329 | /** | |
427c415b FM |
1330 | Specifies whether there is a mask or not. |
1331 | ||
1332 | The area of the mask is determined by the current mask colour. | |
23324ae1 | 1333 | */ |
4cc4bfaf | 1334 | void SetMask(bool hasMask = true); |
23324ae1 FM |
1335 | |
1336 | /** | |
1337 | Sets the mask colour for this image (and tells the image to use the mask). | |
1338 | */ | |
1339 | void SetMaskColour(unsigned char red, unsigned char green, | |
1340 | unsigned char blue); | |
1341 | ||
1342 | /** | |
427c415b FM |
1343 | Sets image's mask so that the pixels that have RGB value of mr,mg,mb in |
1344 | mask will be masked in the image. | |
1345 | ||
1346 | This is done by first finding an unused colour in the image, setting | |
1347 | this colour as the mask colour and then using this colour to draw all | |
1348 | pixels in the image who corresponding pixel in mask has given RGB value. | |
1349 | ||
1350 | The parameter @a mask is the mask image to extract mask shape from. | |
1351 | It must have the same dimensions as the image. | |
1352 | ||
1353 | The parameters @a mr, @a mg, @a mb are the RGB values of the pixels in | |
1354 | mask that will be used to create the mask. | |
3c4f71cc | 1355 | |
d29a9a8a | 1356 | @return Returns @false if mask does not have same dimensions as the image |
427c415b FM |
1357 | or if there is no unused colour left. Returns @true if the mask |
1358 | was successfully applied. | |
1359 | ||
1360 | @note | |
1361 | Note that this method involves computing the histogram, which is a | |
1362 | computationally intensive operation. | |
23324ae1 FM |
1363 | */ |
1364 | bool SetMaskFromImage(const wxImage& mask, unsigned char mr, | |
1365 | unsigned char mg, | |
1366 | unsigned char mb); | |
1367 | ||
1368 | //@{ | |
1369 | /** | |
427c415b FM |
1370 | Sets a user-defined option. The function is case-insensitive to @a name. |
1371 | ||
23324ae1 FM |
1372 | For example, when saving as a JPEG file, the option @b quality is |
1373 | used, which is a number between 0 and 100 (0 is terrible, 100 is very good). | |
3c4f71cc | 1374 | |
4cc4bfaf | 1375 | @see GetOption(), GetOptionInt(), HasOption() |
23324ae1 FM |
1376 | */ |
1377 | void SetOption(const wxString& name, const wxString& value); | |
7c913512 | 1378 | void SetOption(const wxString& name, int value); |
23324ae1 FM |
1379 | //@} |
1380 | ||
1381 | /** | |
427c415b FM |
1382 | Associates a palette with the image. |
1383 | ||
1384 | The palette may be used when converting wxImage to wxBitmap (MSW only at present) | |
1385 | or in file save operations (none as yet). | |
23324ae1 FM |
1386 | */ |
1387 | void SetPalette(const wxPalette& palette); | |
1388 | ||
1389 | /** | |
427c415b FM |
1390 | Sets the colour of the pixels within the given rectangle. |
1391 | ||
1392 | This routine performs bounds-checks for the coordinate so it can be considered | |
1393 | a safe way to manipulate the data. | |
23324ae1 | 1394 | */ |
0a98423e FM |
1395 | void SetRGB(const wxRect& rect, |
1396 | unsigned char red, | |
4cc4bfaf FM |
1397 | unsigned char green, |
1398 | unsigned char blue); | |
23324ae1 | 1399 | |
9d1c7e84 VZ |
1400 | /** |
1401 | Set the type of image returned by GetType(). | |
1402 | ||
1403 | This method is mostly used internally by the library but can also be | |
1404 | called from the user code if the image was created from data in the | |
1405 | given bitmap format without using LoadFile() (which would set the type | |
1406 | correctly automatically). | |
1407 | ||
1408 | Notice that the image must be created before this function is called. | |
1409 | ||
1410 | @since 2.9.0 | |
1411 | ||
1412 | @param type | |
1413 | One of bitmap type constants, @c wxBITMAP_TYPE_INVALID is a valid | |
1414 | value for it and can be used to reset the bitmap type to default | |
1415 | but @c wxBITMAP_TYPE_MAX is not allowed here. | |
1416 | */ | |
1417 | void SetType(wxBitmapType type); | |
1418 | ||
23324ae1 FM |
1419 | /** |
1420 | Returns a resized version of this image without scaling it by adding either a | |
427c415b FM |
1421 | border with the given colour or cropping as necessary. |
1422 | ||
1423 | The image is pasted into a new image with the given @a size and background | |
1424 | colour at the position @a pos relative to the upper left of the new image. | |
1425 | ||
1426 | If @a red = green = blue = -1 then the areas of the larger image not covered | |
1427 | by this image are made transparent by filling them with the image mask colour | |
1428 | (which will be allocated automatically if it isn't currently set). | |
1429 | ||
1430 | Otherwise, the areas will be filled with the colour with the specified RGB components. | |
3c4f71cc | 1431 | |
4cc4bfaf | 1432 | @see Resize() |
23324ae1 | 1433 | */ |
427c415b | 1434 | wxImage Size(const wxSize& size, const wxPoint& pos, int red = -1, |
328f5751 | 1435 | int green = -1, int blue = -1) const; |
23324ae1 FM |
1436 | |
1437 | /** | |
427c415b | 1438 | Assignment operator, using @ref overview_refcount "reference counting". |
3c4f71cc | 1439 | |
7c913512 | 1440 | @param image |
4cc4bfaf | 1441 | Image to assign. |
3c4f71cc | 1442 | |
d29a9a8a | 1443 | @return Returns 'this' object. |
23324ae1 | 1444 | */ |
5267aefd | 1445 | wxImage& operator=(const wxImage& image); |
23324ae1 FM |
1446 | }; |
1447 | ||
23324ae1 FM |
1448 | // ============================================================================ |
1449 | // Global functions/macros | |
1450 | // ============================================================================ | |
1451 | ||
8cd06fb5 BP |
1452 | /** @ingroup group_funcmacro_appinitterm */ |
1453 | //@{ | |
1454 | ||
23324ae1 FM |
1455 | /** |
1456 | Initializes all available image handlers. For a list of available handlers, | |
1457 | see wxImage. | |
7c913512 | 1458 | |
4cc4bfaf | 1459 | @see wxImage, wxImageHandler |
027c1c27 BP |
1460 | |
1461 | @header{wx/image.h} | |
23324ae1 FM |
1462 | */ |
1463 | void wxInitAllImageHandlers(); | |
1464 | ||
8cd06fb5 BP |
1465 | //@} |
1466 |