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